Connect a customer | Documentation for the Hill Labs API

Outcome

Connect a customer by redirecting their browser to mylab. After they approve your app, mylab redirects their browser to your registered callback, where your app exchanges the authorisation code for an access token.

Before you start

Your third-party app and callback URL must be registered with Hill Labs. Use the environment-specific authorisation URL, token endpoint, client ID, results scope, audience and API base URL supplied during onboarding.

1. Send your customer to mylab

Prompt your customer to choose Connect to Hill Labs or the equivalent action in your app.
Generate a cryptographically random state value and PKCE verifier. Create an S256 challenge from the verifier.
Redirect your customer's browser to the supplied mylab authorisation URL with the registered client ID and callback URL, the results scope, response_type=code, state, code_challenge and code_challenge_method=S256.
Your customer signs in to mylab if needed, reviews the request and chooses Allow access or Decline. You can use the same browser tab or a separate window, as long as you use the registered callback.

mylab displays your registered third-party app name and explains the requested results access. mylab never shares your customer's password. mylab uses the account your customer signs in with to determine which results they can access. You cannot request another customer's results by adding their customer ID to an API request.

Authorisation request fields

Field	Purpose
`response_type=code`	Requests an authorisation code.
`client_id`	Identifies the third-party app registered with Hill Labs.
`redirect_uri`	Must exactly match a callback registered for the application.
`scope`	The environment-specific results-read scope supplied during onboarding.
`state`	A random value your application checks when the browser returns.
`code_challenge` and `code_challenge_method=S256`	Bind the code exchange to the original PKCE verifier.

2. Exchange the authorisation code

After approval, mylab redirects to the registered callback with a short-lived, one-time authorisation code and the original state. Check that state matches before sending the code and original PKCE verifier to the token endpoint.

POST {token_endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client_id}
&code={authorisation_code}
&redirect_uri={registered_callback}
&code_verifier={original_pkce_verifier}

If your customer declines, mylab returns an access-denied response instead of an authorisation code. Do not mark the connection as approved or call the results API.

3. Use the access token

Use the returned access token as a bearer token for Connected Apps results requests. Keep tokens out of URLs and application logs. Store any refresh token securely and replace it when it rotates; see Keep access working for refresh and recovery.

Authorization: Bearer {partner_access_token}
Accept: application/json

Remembered approval

mylab remembers an active approval for the same customer, registered third-party app and exact results scope. When your customer connects again, mylab still authenticates them but skips the consent screen while that approval remains active. If a different customer connects, you change the app registration or requested scope, or the grant has been revoked, ask the customer to approve a new request.

Next step

Continue to Find and retrieve results.