Authenticating with Access Tokens

This is a guide to logging in as a user using Access Tokens. This is useful when your users already use a separate system to manage their service.

Generate access token

To begin logging in as a user, you will need to generate an access token. You can do this by making a request to the access_tokens/create endpoint. You will need to pass the ID of the entity you want to log in as, and the role you want to log in as.

Additionally, you can customise the customer portal by passing options to the options hash. You can view a full list of options within our API documentation.

Request

 curl https://connectapi.dial9.co.uk/api/v2/access_tokens/create \
  -H "X-Auth-Token: XXX" \
  -H "X-Auth-Secret: XXX" \
  -H "Content-Type: application/json" \
  -d '{"entity":"unit_qUhedVgTolRIotE9", "role":"Phone System Owner", "options":{"full_name":"Gertrude Jekyll", "email_address":"gertrude.jekyll@example.com" } }'

Response

{
  "status": "success",
  "time": 0.04,
  "flags": {},
  "data": {
    "id": "at_daKE5IjS951iymwP",
    "url": "https://example.voipcloud.uk/login/xxx",
    "options": {
      "full_name": "Gertrude Jekyll",
      "email_address": "gertrude.jekyll@example.com",
      "on_logout_url": null,
      "header_link_text": "Back to Portal",
      "header_link_url": null,
      "time_zone": "London",
      "time_format": "default"
    }
  }
}

Using the access token

Once you have generated an access token, you can use it to log in as the user by redirecting the user to the URL in the url field. The URL will be valid for 30 seconds, and can be used to log in once. If you need to log in as the user again, you will need to generate a new access token.

When the user logs out of the customer portal

If the on_logout_url option is set when you create the access token, the user will be redirected to this URL after they log out of the customer portal. The URL will be appended with a ?token= parameter containing a JWT token that is signed using the JWT secret located within the settings area.

The JWT token will contain the following claims:

• nbf - The time the token is not valid before, which will be the current time
• exp - The time the token expires, which will be the current time plus 30 seconds
• sub - The subject of the token, which will be the ID of the access token
• reason - The reason for the logout, which will be one of logout or session_expired

You should validate the JWT token before using it, and ensure that the nbf is not in the future, the exp claim is not in the past and the sub matches the id of the access token you used to log the user in with.

You can use the jwt.io website to verify the token.

Logging out a user from the customer portal using JWT

When a user logs out of your own system, you can log them out of the customer portal by redirecting the user to your portal logout URL appended with a ?token= parameter containing a JWT token that is signed using your secret. For example, if your portal domain is https://example.voipcloud.uk the logout URL would be https://example.voipcloud.uk/logout?token=XXX.

The JWT token MUST contain the following claims and be signed using the HS256 algorithm using your JWT secret.

• sub - The access token ID
• nbf - The time the token was issued
• exp - The time the token expires - this should be less than 30 seconds from the time the token was issued

Optionally, you can also include the following claims:

• return_url - The URL to redirect the user to after they have been logged out of the portal