Authenticate

Who this is for

Engineers making their first call. By the end of this step you hold an access token that identifies you and your organisation.

How authentication works

Every request is made to the gateway with a bearer token. The token carries two claims that matter to you:

Claim	Meaning
`sub`	The calling principal: a user or a machine client
`tenant_id`	The organisation every request is scoped to

The gateway verifies the token's signature, issuer and expiry. A missing, expired or malformed token is rejected with 401.

You get a token from POST /api/auth/login with an email address and password. The response carries an accessToken, a refreshToken, and expiresIn (the access token's lifetime in seconds). Before the access token expires, exchange the refresh token for a new one at POST /api/auth/refresh.

This Quickstart signs in as a user, which is the flow the API Reference documents.

Machine clients. A bank system that calls the API without a person uses the OAuth 2.0 client credentials grant instead. It authenticates to the identity provider's token endpoint and receives a short-lived access token, which it sends as the bearer token in the same way. In a client-hosted deployment the identity provider is the bank's own, and the bank issues and rotates the client credentials. Suspending a client, or signing it out globally, stops new tokens being issued; a token already issued stays valid until it expires. See Authentication. Obtain the identity-provider token endpoint, client identifier and credential format during onboarding. The user login endpoint is not a client-credentials token endpoint.

First sign-in: activate your invited account

An invited user receives an email with a temporary password. Activate the account and choose a password in one call.

POST /api/auth/activate HTTP/1.1
Host: api.qfp.quantnetwork.net
API-Version: 1.0.0
Content-Type: application/json

{
  "email": "[email protected]",
  "temporaryPassword": "Temp!2345",
  "newPassword": "Ch0sen!Passw0rd"
}

Illustrative example built from the schema.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accessToken": "eyJraWQiOiJ...",
  "refreshToken": "eyJjdHkiOiJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

The temporary password is spent on success and the account becomes ACTIVE.

You can also do this in two calls. Sign in with the temporary password. The response carries challenge: NEW_PASSWORD_REQUIRED and a session value, and no token. Then answer the challenge at POST /api/auth/new-password with email, newPassword and that session.

Worked example: sign in

POST /api/auth/login HTTP/1.1
Host: api.qfp.quantnetwork.net
API-Version: 1.0.0
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "S3cret!Passw0rd"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accessToken": "eyJraWQiOiJ...",
  "refreshToken": "eyJjdHkiOiJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Send the access token on every later request:

Authorization: Bearer eyJraWQiOiJ...

If the account still needs a new password, the same call returns the challenge instead of tokens. The two outcomes never appear together, and absent fields are omitted:

{
  "challenge": "NEW_PASSWORD_REQUIRED",
  "session": "AYABeC..."
}

Answer it:

POST /api/auth/new-password HTTP/1.1
Host: api.qfp.quantnetwork.net
API-Version: 1.0.0
Content-Type: application/json

{
  "email": "[email protected]",
  "newPassword": "Ch0sen!Passw0rd",
  "session": "AYABeC..."
}

The response is 200 with the same token fields as a sign-in, and never a challenge.

View in API Reference

Sign in · POST

Answer the NEW_PASSWORD_REQUIRED challenge · POST

Worked example: refresh the access token

POST /api/auth/refresh HTTP/1.1
Host: api.qfp.quantnetwork.net
API-Version: 1.0.0
Content-Type: application/json

{
  "refreshToken": "eyJjdHkiOiJ..."
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accessToken": "eyJraWQiOiJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

No new refresh token is returned. Keep the one issued at sign-in until it expires, then sign in again. The refresh-token lifetime is set by the identity provider. Handle refresh rejection by signing in again rather than assuming a fixed lifetime.

View in API Reference

Refresh the access token · POST

Errors and edge cases

Status	When	What to do
`400`	The body failed validation. A field violation reads `Invalid Request parameter. {field}`; unreadable JSON reads `Malformed JSON request`	Fix the request
`401` on sign-in	Wrong credentials, or the account has no platform user, no organisation, or a status other than `ACTIVE`. The message is always `Invalid credentials.`	Check the credentials and account status with your administrator. The message is the same for every cause by design
`401` on activation	Wrong temporary password, or the account was already activated	Sign in with the chosen password instead
`401` on refresh	The refresh token is expired or revoked, or the account is disabled. The message is always `Refresh token is invalid or expired.`	Sign in again
`500`	The sign-in service returned neither tokens nor a challenge	Retry later. Use bounded backoff for temporary sign-in failures and stop on invalid credentials. Avoid a tight retry loop or logging passwords.

Example 401:

Illustrative example built from the schema.

{
  "timestamp": "2026-08-03T09:20:02.114Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials."
}

Password complexity rules: Choose a new password that meets the identity provider's policy supplied during onboarding. Handle a rejected password through the returned error; do not infer complexity rules from an example..

API Reference

Open an endpoint for request fields, response examples and the interactive API console.

Operation	Method
Sign in	`POST`
Refresh the access token	`POST`
Answer the NEW_PASSWORD_REQUIRED challenge	`POST`
Activate an invited account in one call	`POST`

Implementation resources

Auth code recipes.

Use Implement a backend client for request handling, durable idempotency and outcome tracking. The developer integration coverage map links every public operation to its API Reference and contract-derived code recipe. Replace example identifiers with values from your assigned environment.