Introduction

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

Rate limits

ReachFive APIs employ a number of safeguards against bursts of incoming traffic for each tenant, to help maximize its stability. Rate liming allows to change the maximum number of calls from the same IP, within a defined time frame.

When an IP reaches the limit, the server responds 429 Too Many Requests.

By default, all endpoints below allow 100 requests every 60 seconds, from the same IP.

  • /identity/v1/password/login*
  • /identity/v1/signup*
  • /identity/v1/signup-token*
  • /identity/v1/passwordless/start
  • /identity/v1/verify-auth-code
  • /identity/v1/forgot-password
  • /identity/v1/update-password
  • /identity/v1/passwordless/verify
  • /identity/v1/lite-registration
  • /oauth/token
  • /oauth/revoke
  • /link/verify-email/:token

Endpoints with a * have a configurable rate limit, which you set in the ReachFive console (Settings > Security > Rate limiting).

Whitelisting IPs

Under Global settings > Allowed IP addresses, enter IPs addresses to whitelist. Subsequent calls from these IPs will not be submitted to any rate limit.

Warning: Whitelisting removes rate limits on all API endpoints and for all clients of the same ReachFive tenant, for these IPs addresses.

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.

Note: Refreshing access tokens using an expired refresh token fails and invalidates all refresh tokens issued previously, for this ReachFive client only (client_id).

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
}

Revoke Refresh Token

Use this endpoint to revoke a Refresh Token.

Arguments
  • 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 to revoke.

Response

204 No Content

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

{
  "client_id": "slNIt...yKzQM",
  "client_secret": "dYEa3...3z2m2",
  "refresh_token": "XpcgV...5sSY5"
}

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.

  • client_secret

    required string

    Your client Secret.

Response

Note: The response contains the custom claim https://reach5.co/login-as (true) if the access token was generated via the Login As endpoint. The associated refresh and id tokens do not bear this claim.

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: application/json
{
  "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",
  "https://reach5.co/login-as": true
}

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

Emails

Verify email address

Checks the validity of the email address supplied by a user during sign-up.

Arguments
  • token

    required string

    String containing the email address and a random code generated during sign-up.

  • cliend_id

    required string

    Your ReachFive Client ID.

  • redirectUrl

    string

    URL to redirect the user to after email validation.

    If no URL is passed, the redirect URL set in the ReachFive console is used (Emails > Templates > Verification email > Redirect to).

Response

HTTP 303 - redirects the user to the redirectUrl. In case of an error, the code and description are passed as query string parameters to the redirectUrl.

Definition
GET /link/verify-email/:token?client_id=YOUR_CLIENT_ID&redirectUrl=url
Example Request
GET /link/verify-email/XpcgV...5sSY5?redirectUrl=https://reachfive.com 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"
    }
  ]
}