Home Admin guide Platform API Methods for authenticating users

Methods for authenticating users

Authentication occurs according to the SSO scheme (single sign-on) based on the OAuth 2.0 standard.

Use these methods to manage user access to the exchange:

POST[host]/identity/sign-in

GET[host]/identity/connect/authorize

POST[host]/identity/connect/token

Sign in as an admin

POST[host]/identity/sign-in

Sign in using 2FA

POST[host]/identity/connect/token

Sign in Machine-to-Machine

POST[host]/identity/connect/token

Obtain refresh token

POST[host]/identity/sign-out

Sign out

Sign in as an admin

First, a sign-in request must be sent to obtain cookies.

Request

Body:

email string required

Your Admin Panel login.

password string required

Your Admin Panel password.

POST[host]/identity/sign-in

POST /identity/sign-in HTTP/1.1
Host: host.name

{
  email: "admin@mail.com", 
  password: "P@ssw0rd"
}

Response

secondFactorRequired boolean

If true, an additional POST-request containing a 2FA code must be sent before proceeding with authorization.

message string

The notification message. Applicable only if secondFactorRequired is true.

provider string

The method of sending a one-time 2FA code. Applicable only if secondFactorRequired is true.

RESPONSE EXAMPLE 
{
  "secondFactorRequired": true,
  "message": "For your security, we have emailed you a one-time authentication code. Please enter this code below to proceed.",
  "provider": "Email"
}

Note

If authorization is successful, cookies are provided, which are valid only for a corresponding IdentityServer.

Next, a request must be sent to obtain the xmlHttpRequest.responseURL code.

Request

Query parameters:

The parameters are described in the OAuth 2.0 specification. The PKCE extension (Proof Key for Code Exchange) is used to further ensure session security.

client_id required

The client identifier:

  • spa — for Front Office only; the following scopes are available for spa clients:

    openid offline_access FrontOffice

  • spa_admin — for Front Office and Back Office; the following scopes are available for spa_admin clients:

    openid offline_access FrontOffice BackOffice

redirect_uri required

The absolute path to a sign-in-done page at the IdentityServer address, which is used after successfully signing in (for example, https://host.name/sign-in-done). Relative paths are not supported.

GET[host]/identity/connect/authorize

GET /identity/connect/authorize
  ?client_id=spa_admin
  &response_type=code
  &scope=openid%20profile%20FrontOffice%20BackOffice%20offline_access
  &redirect_uri=https://staging.tech/sign-in-done
  &state=f27332fa-4e7a-4a82-a586-00e58ec63333
  &nonce=da4a8d26-9518-44c3-9e63-3a199dca8f14
  &code_challenge=suB-wE8Qkr-AvzFA3bvyX597BYq_GX-S5-N-5B5UMOU
  &code_challenge_method=S256 HTTP/1.1
Host: host.name

Response

In response, a redirect URL is sent containing the required code, which is one-time and cannot be reused.

In case of incorrect input data, identity/unauthorized is returned with HTTP code 401.

RESPONSE EXAMPLE 
Location: https://staging.tech/sign-in-done
  ?code=ebd6574c9a734ec47b375dbfff951964a8935e0e9690a00be80b54a3d7ff48b2
  &scope=openid%20profile%20FrontOffice%20BackOffice%20offline_access
  &state=f27332fa-4e7a-4a82-a586-00e58ec63333
  &session_state=QjgS-hVe-y9rdqjIKxHyf4Jp9iT8uFxIijYsnHuRIoU.1a16e4bc02f924a173a684122e41c5ce

To complete authorization, send another request to obtain the access and refresh tokens.

Request

Header parameters:

  • Content-Type: application/x-www-form-urlencoded

  • Authorization: Basic base64(ClientId:ClientSecret)

Query parameters:

The parameters are described in the OAuth documentation. An additional round trip to the server is required for code_verifier.

POST[host]/identity/connect/token

POST /identity/connect/token HTTP/1.1
Host: staging.tech
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c3BhX2FkbWluOnNwYV9hZG1pbl9zZWNyZXQ=

grant_type=authorization_code
    &code=49b3960d01d195a4330649fb711d0e41863573ccad4324714549d70623867d6d
    &code_verifier=a2cd48e5-8a13-4529-...-ad4e-a59b7edb87d8
    &redirect_uri=https%3A%2F%2Fhost.nameh%2Fsign-in-done

Response

access_token string

The access token that expires in 30 seconds after which it must be refreshed.

expires_in number

The access token expiration time, in μs.

token_type string

Always Bearer.

refresh_token string

The long-living token which is used for obtaining new access tokens.

scope string

The scope for a spa client.

RESPONSE EXAMPLE 
{
  "access_token": "eyJhbGci...0MkP_NUQ",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "4f6c4...676u67u6",
  "scope": "FrontOffice offline_access openid"
}

Sign in using 2FA

If secondFactorRequired is true, an additional POST-request containing a one-time 2FA code must be sent to the same endpoint.

Request

Body:

provider string required

The method of sending a one-time 2FA code.

VerificationCode string required

The one-time 2FA code.

POST[host]/identity/sign-in

POST /identity/sign-in HTTP/1.1
Host: host.name

{
  "provider": "Email",
  "VerificationCode": "123456"
}

Response

In response, VerificationCode is sent to the email specified in the request.

RESPONSE EXAMPLE 
{
  "secondFactorRequired": false,
  "account": {
    "nickname": "admin",
    "email": "admin@mail.com",
    "id": "8ac0a52e-f516-5bb2-009c-0ec8a23a9f49"
  }
}

Sign in [Machine-to-Machine]

Important

This authentication method is for internal use only: it must only be used between trusted servers.

Two-factor authentication is not applicable for this authentication method.

Request

Header parameters:

Note

This endpoint does not support JSON in the request.

  • Content-Type: application/x-www-form-urlencoded

  • Authorization: Basic base64(ClientId:ClientSecret)

Query parameters:

The parameters are described in the OAuth specification.

ClientId

The client identifier. The following values are supported:

  • lk

  • tests

ClientSecret

The client secret. Please contact your exchange service provider to clarify this value for your environment.

scope

The scope. Possible values:

  • openid offline_access FrontOffice

  • openid offline_access BackOffice

POST[host]/identity/connect/token

POST /identity/connect/token HTTP/1.1
Host: host.name
Content-Type: application/x-www-form-urlencoded

grant_type=password
  &username=johndoe
  &password=A3ddj3w
  &scope=openid%20FrontOffice%20offline_access

Response

access_token string

The access token that expires in 30 seconds after which it must be refreshed.

expires_in number

The access token expiration time, in μs.

token_type string

Always Bearer.

refresh_token string

The long-living token which is used for obtaining new access tokens.

scope string

The scope for a spa client.

RESPONSE EXAMPLE 
{
  "access_token": "eyJhbGci...0MkP_NUQ",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "4f6c4...676u67u6",
  "scope": "FrontOffice offline_access openid"
}

Obtain the refresh token

Request

Header parameters:

  • Content-Type: application/x-www-form-urlencoded

Query parameters:

New tokens are obtained according to the OAuth 2.0 documentation. The refresh token is one-time and cannot be reused.

POST[host]/identity/connect/token

POST /identity/connect/token HTTP/1.1
Host: host.name
Content-Type: application/x-www-form-urlencoded

client_id=spa_admin
  &client_secret=spa_admin_secret
  &grant_type=refresh_token
  &refresh_token=ad46d62576fa4510318d1e5e759f0ff18c4925...
  &scope=openid%20offline_access%20BackOffice%20FrontOffice

Response

access_token string

The access token that expires in 30 seconds after which it must be refreshed.

expires_in number

The access token expiration time, in μs.

token_type string

Always Bearer.

refresh_token string

The long-living token which is used for obtaining new access tokens.

RESPONSE EXAMPLE 
{
  "access_token": "akvmn34egjidg0jifgjdg0djg34g",
  "token_type": "Bearer",
  "refresh_token": "dfk3glhlkskmnksdgnfkog",
  "expires_in": 3600
}

Sign out

After signing out, the access token continues to be valid until it expires (the default lifetime is 30 seconds). The token should be removed from the client-side local storage.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Body:

refresh_token string

If no refresh token is provided, all refresh tokens previously issued for the current user are revoked along with corresponding client identifiers (clientId). In this case, the request body must be an empty JSON object: { }

POST[host]/identity/sign-out

POST /identity/sign-out HTTP/1.1
Host: host.name
Authorization: Bearer akvmn34egjidg0jifgjdg0djg34g

{
  "refresh_token": "refresh_token"
}

Response

In case of success, HTTP code 200 is returned.