Introduction

This documentation contains all Identity and Authentication related endpoints that can be called from your web application server.

Get tokens

Authorization Code

This is the OAuth 2.0 grant that web apps utilize in order to access an API. Use this endpoint to exchange an Authorization Code for a Token.

Arguments
  • grant_type

    required string

    Must be set to authorization_code.

  • client_id

    required string

    Your client ID.

  • client_secret

    string

    Your client Secret. Required if your Client’s authorization method is Post.

  • code

    required string

    The authorization code received from the initial authorization call.

  • redirect_uri

    required string

    The redirect_uri parameter value included in the authorization request.

Returns

Definition
POST /oauth/token
Example Request
POST /oauth/token HTTP/1.1
Host: https://YOUR_DOMAIN
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "slNIt...yKzQM",
  "client_secret": "dYEa3...3z2m2",
  "code": "XpcgV...5sSY5",
  "redirect_uri": "https://example.com/callback"
}
Example Response
{
  "access_token": "tb37Sz...h3eh6q",
  "id_token": "eEoQAi...yJ04ae",
  "refresh_token": "djnxBN...eXbEbL",
  "token_type": "Bearer",
  "expires_in": 86400
}

Refresh Token

Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization.

Arguments
  • grant_type

    required string

    Must be set to refresh_token.

  • client_id

    required string

    Your client ID.

  • client_secret

    string

    Your client Secret. Required if your Client’s authorization method is Post.

  • refresh_token

    required string

    The Refresh Token.

Returns

Definition
POST /oauth/token
Example Request
POST /oauth/token HTTP/1.1
Host: https://YOUR_DOMAIN
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "slNIt...yKzQM",
  "client_secret": "dYEa3...3z2m2",
  "refresh_token": "XpcgV...5sSY5"
}
Example Response
{
  "access_token": "tb37Sz...h3eh6q",
  "refresh_token": "djnxBN...eXbEbL",
  "id_token": "eEoQAi...yJ04ae",
  "token_type": "Bearer",
  "expires_in": 86400
}

Introspection

This endpoints returns the content of an access token.

It has two conditions: it must be called from an authenticated client, and the client needs to come from the same account as the token. In addition, third-party clients can only read tokens that were generated using the same client (first-party clients can read any access token of the same account).

See RFC 7662 for more details.

Arguments
  • token

    required string

    Token to decode. Must be passed as a query string.

  • client_id

    required string

    Your client ID. Must be passed as form data in the POST body.

  • client_secret

    required string

    Your client Secret. Must be passed as form data in the POST body.

Returns

Definition
POST /identity/v1/token-info
Example Request
POST /identity/v1/token-info?token=tb37Sz...h3eh6q HTTP/1.1
Host: https://YOUR_DOMAIN
Content-Type: x-www-form-urlencoded

client_id=slNIt...yKzQM&client_secret=dYEa3...3z2m2
Example Response
{
  "iss": "your-site.com",
  "aud": ["YOUR_DOMAIN/identity"],
  "iat": 1553868034,
  "scope": "openid email profile",
  "clientId": "ryQ45...ztD7",
  "name": "Bruce Wayne",
  "email": "bruce@wayne.com"
}

Lite Registration

Push lite profile

Pushes lite profile.

Returns

Definition
POST /identity/v1/lite-registration
Example Request
POST /identity/v1/lite-registration HTTP/1.1
Host: https://YOUR_DOMAIN
{
  "email": "bruce.wayne@wayne.com",
  "birthdate": "1981-10-13",
  "nickname": "Batman"
}
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt"
}

User profile

Get user profile

Retrieve user's profile.

Arguments
  • fields

    string

    User’s fields to retrieve in the response. Defaults to id,name,email.

Returns

The user's profile

Definition
GET /identity/v1/me
Example Request
GET /identity/v1/me?fields=id,given_name,family_name,email,birthdate HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer eyJ0eXAiOiJKV1QiL...
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@exemple.com",
  "birthdate": "1983-11-13"
}

Update user profile

Update user's profile.

Arguments
  • fields

    string

    User’s fields to retrieve in the response. Defaults to id,name,email.

Returns

The user's profile

Remarks

  • email and password fields are not modifiable with this endpoint, expect for a new user without email (generally when not provided by the social provider).

  • phone_number field is not modifiable if sms verification code is enabled on the account settings.

Definition
POST /identity/v1/update-profile
Example Request
POST /identity/v1/update-profile HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer eyJ0eXAiOiJKV1QiL...

{
  "birthdate": "1981-10-13"
}
Example Response
{
  "id": "AVqvOB58Fg6nZfQ0ZqXt",
  "name": "John Doe",
  "email": "john.doe@example.com"
}