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 endpoint returns the content of an access token.

It has two conditions:

  1. It must be called from an authenticated client.
  2. The client must belong to the same account as the token.

In addition, third-party clients can only read tokens which they generated. 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.

  • Fields not required can be deleted by using null value, except for custom fields and consents.

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"
}

User events

Search user's events

Search and retrieve user's events.

Scope:  events

Arguments
  • filter

    string

    Search criteria. More informations here.

  • fields

    string

    Fields to retrieve.

  • page

    integer

    Page number. One based. Defaults to 1.

  • count

    integer

    Amount of items per page. Defaults to 20.

  • sort

    string

    Field to use for sorting. Use field:order where order is asc for ascending and desc for descending. For example date:desc.

Returns

A search result with the number of results and a list of user's events

Definition
GET /identity/v1/userevents
Example Request
GET /identity/v1/userevents?filter=type%20%3D%3D%20%22login%22 HTTP/1.1
Host: https://YOUR_DOMAIN
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Response
{
  "total": 2,
  "items": [
    {
      "date": "2019-06-17T08:57:13.000Z",
      "auth_type": "password",
      "ip": "127.0.0.1",
      "type": "login",
      "client_id": "YOUR_CLIENT_ID",
      "provider": "password",
      "user_id": "YOUR_PROFILE_ID",
      "profile_id": "YOUR_PROFILE_ID",
      "login_time": "2019-06-17T08:57:13.000Z",
      "host": "https://YOUR_DOMAIN",
      "id": "AWsnrYqDxUXWdPYi1aPI",
      "device": "desktop",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:69.0) Gecko/20100101 Firefox/69.0"
    },
    {
      "date": "2019-06-19T10:12:13.000Z",
      "auth_type": "password",
      "ip": "127.0.0.1",
      "type": "login",
      "client_id": "YOUR_CLIENT_ID",
      "provider": "password",
      "user_id": "YOUR_PROFILE_ID",
      "profile_id": "YOUR_PROFILE_ID",
      "login_time": "2019-06-19T12:12:13.385Z",
      "host": "https://YOUR_DOMAIN",
      "id": "AWtvptgcRsnAuaJCTBdT",
      "device": "desktop",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:69.0) Gecko/20100101 Firefox/69.0"
    }
  ]
}