Authorizing an account
To authorize an account, send the following request:
POST /auth/api/v1/authentication-management/session{
email: 'string', //The user’s email address
signature: 'string', //The signature of the user’s email address encoded as Hex
authPublicKeyHex: 'string', //The public key of the authorization key pair encoded as Hex
authCode: 'string', //Optional. The one-time code of the second sign-in step: the emailed code or the code of the authenticator app
method: 'string' //Optional. Which second step the code answers: 'email' or 'totp'
}{
email: 'analyst@example.com',
signature: '5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05',
authPublicKeyHex: '01e2dd1324317845a8cbac08a1f1709e634dc393e365bbc5dd29fc2bd2b6b69e'
}NOTE
For instructions on how to generate the signature string, see Signing user email addresses.
The authPublicKeyHex string is taken from the user's Authorization key on the web app Profile page. For details, see Profile and security: Keys for the API. Send it as it is shown there: 64 lower-case hex characters, without a 0x prefix.
The email must be written exactly as it was registered, letter case included. The signature is made over that text.
The example uses the public test vector.
The signature string must be produced with the private key of that same authorization key pair. A request signed with the signing key pair is rejected with a 401 response (InvalidSignature).
Expected result
If authorization is successful, a response with the following JSON web tokens is generated:
| Field | Value Type | Description |
|---|---|---|
accessToken | string | The access token, which is later sent with every other request in the header Authorization: Bearer <accessToken>. Valid for 5 minutes. |
refreshToken | string | The refresh token, used to get a new pair of tokens without signing in again. Valid for 24 hours. |
expirationTime | string | The exact time the access token expires (ISO 8601: YYYY-MM-DDTHH:MM:SSZ). It is the exp claim of the access token. |
{
status: {
code: integer($int32),
name: 'string'
},
data: {
accessToken: 'string',
refreshToken: 'string',
expirationTime: 'string'
}
}{
status: {
code: 0,
name: 'Ok'
},
data: {
accessToken: 'eyJhbGciOiJFZERTQSJ9.<payload>.<signature>',
refreshToken: 'eyJhbGciOiJFZERTQSJ9.<payload>.<signature>',
expirationTime: '2026-11-13T12:51:54Z'
}
}Second sign-in step
If the account has a second sign-in step, the first request does not return tokens. What it answers depends on the method that is asked first for the account:
| Method | First answer | What to send next |
|---|---|---|
| Emailed code | 428 with code 65. A one-time code is emailed to the user. | The same request with the code in authCode. |
| Authenticator app | 428 with code 80. data is an object that lists the methods of the account in methods and the one asked first in preferred. | The same request with method: 'totp' and the 6-digit code of the app in authCode. |
| Passkey | 428 with code 80, as above, with the passkey options in data.passkey. | A passkey is answered by a browser. An API client cannot use it. |
// 428, the account has an authenticator app
{
status: {
code: 80,
name: 'TwoFactorRequiredError',
message: 'A second sign-in step is required'
},
data: {
methods: ['totp'],
preferred: 'totp'
}
}// The second request
{
email: 'analyst@example.com',
signature: '5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05',
authPublicKeyHex: '01e2dd1324317845a8cbac08a1f1709e634dc393e365bbc5dd29fc2bd2b6b69e',
method: 'totp',
authCode: '123456'
}- A request that names a method the account has not set up answers
409with code75. - A wrong code answers
422with code64. - For an account that an integration signs in with, set up the emailed code or the authenticator app, not only a passkey. If the account also has a passkey, send
methodwith the method you use.
For details, see API reference > Sign in.
Keeping the session
- The access token is valid for 5 minutes. Before it expires, refresh the tokens with the refresh token.
- A refresh replaces both tokens. The refresh token works once, and the access token issued before the refresh stops working at once. Use the pair of the latest answer for every request that follows.
- The tokens carry the state of the account at the time they were issued. After an account is approved, it can use the other endpoints from its next token on: refresh the tokens or sign in again.
If authorization is unsuccessful, refer to API reference > Sign in for a list of possible reasons.