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.

Response

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.

Response

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.

Response

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

Passwordless

Start passwordless email

Starts passwordless flow by sending an email to the user with a single-use auth code or access token (depending on use of code or token value for the response_type parameter). We recommend using code to ensure a more secure connection using the auth code flow.

Response

Returns HTTP 204. An email will be sent to the specified address.

Definition
POST identity/v1/passwordless/start
Example Request
POST identity/v1/passwordless/start HTTP/1.1
Host: https://YOUR_DOMAIN
{
  "client_id": "YOUR_CLIENT_ID",
  "response_type": "code",
  "scope": "openid profile email phone",
  "display": "page",
  "redirect_uri": "https://your-redirect-URI/login/callback",
  "email": "batman@gmail.com"
}

Verify email passwordless

For an email based passwordless flow, the user will click the link provided in the email which will execute the following request. No development is required on your side. You must ensure the redirect_uri provided earlier points to a page where the ReachFive SDK is running.

Response

Returns HTTP 303. The user will begin a classic code or implicit flow from this point onwards, and eventually be redirected to the specified redirect_uri with an access token.

Definition
GET /identity/v1/passwordless/verify
Example Request
GET /identity/v1/passwordless/verify HTTP/1.1
Host: https://YOUR_DOMAIN

Start SMS passwordless

This method is similar to the email equivalent, but sends an SMS to the user instead of an email. The SMS feature must be activated for your ReachFive account in order for this flow to work.

Response

Returns HTTP 204.

Definition
POST /identity/v1/passwordless/start
Example Request
POST /identity/v1/passwordless/start HTTP/1.1
Host: https://YOUR_DOMAIN
{
  "client_id": "YOUR_CLIENT_ID",
  "response_type": "code",
  "scope": "openid profile email phone",
  "display": "page",
  "redirect_uri": "https://your-redirect-URI/login/callback",
  "phone_number": "+33633445566"
}

Verify SMS auth code

Used to check the validity of the code in your front-end, before calling the next call which will redirect the user. This does not consume the single-use code.

Response

Returns HTTP 204 if the code is valid for the given phone number.

Definition
POST /identity/v1/verify-auth-code
Example Request
POST /identity/v1/verify-auth-code HTTP/1.1
Host: https://YOUR_DOMAIN
{
  "verificiation_code": "VERIFICATION_CODE_SENT_BY_SMS",
  "phone_number":"+33633445566"
}

Verify SMS passwordless

This method is used to log the user in by initiating the code flow using the SMS verification code. If you're unable to support the code flow, you can use a response_type=token in your previous requests to directly obtain an access token - but this is not recommended.

Definition
GET /identity/v1/passwordless/verify
Example Request
GET /identity/v1//verify?email=testemail%40reach5.co&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Flogin%2Fcallback&client_id=yourClientID&verification_code=123456&response_type=code HTTP/1.1
Host: https://YOUR_DOMAIN

Lite Registration

Push lite profile

Pushes lite profile.

Response

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.

Response

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.

Response

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.

Response

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