Token-based authentication - quick start

Introduction

Before you can access or manipulate the different resources that are available, you have to get a token. When you are accessing or manipulating the resources, you have to provide this token in your request-header.

The token is needed to authenticate and authorize your calls.

Currently two OAuth 2.0 authorization grants is supported "Resource owner password credentials grant" and "Client credentials grant". We also provide our own Ambita authorization flow "Trusted grant".

Before you can use the Ambita-APIs including the authentication-API, you need to request a token.

A prerequisite for requesting a token is to obtain a client and a client secret(And possible a user and password, depending on the grant_type). In order to obtain this information is a manual process and you need to contact Ambita Customer Service.

How to request a Token

To request a token you use the authentication service. This service has a resource called token. On the token resource, you can use the POST method to get the authentication service to generate a token for you. When posting this request you have to provide some credentials.

There are three ways to authenticate and obtain a token: Client credentials grant, Password credentials grant and Trusted grant.

A client credentials flow is used when the application/client/app authenticates themselves and the actual user does not have to log in with their own credentials. This scenario also cover machine-to-machine communication, not involving a user directly.

Using the Password grant the users will authenticate themself with their own valid username and password. The Password “grant type” is used when you have communication between user and machine.

The Trusted flow is used when the application/client/app already have authenticated the user and wants to request a token for the logged in user without having to request for the users password again. We trust that the client has authenticated the user and knows who it is.

The parameters to the token services are handed over as form data of content type application/x-www-form-urlencoded.

Client credentials grant

To obtain an access (and refresh) token you must call the token service POST /authentication/v2/token. Required parameters are:

grant_type=client_credentials
client_id=<your id>
client_secret=<your secret>
scope (optional)

Parameters must be send using MIME type application/x-www-form-urlencodedor application/json.

  https://beta-api.ambita.com/authentication/v2/token
  client_id=anClientId&client_secret=theSecret&grant_type=client_credentials

If authentication is successful, a JSON will be returned:

{
  "access_token" : "091ec7e2-40c5-43ea-9fb8-13e9f50b6db0",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "4db616c4-c72e-4022-96cc-f95816185531",
  "scope":[]
}

Password credentials grant

To obtain an access (and refresh) token you must call the token service POST /authentication/v2/token. Required parameters are:

For confidential clients the following parameters are required:

grant_type=password
client_id=<your id>
client_secret=<your secret>
username=<user's logon ident>
password=<user' password>

For non-confidential clients the following parameters are required:

grant_type=password
client_id=<your id>
username=<user's logon ident>
password=<user' password>

Username and password are credentials registered in the Ambita Usercatalog. Parameters must be send using MIME type application/x-www-form-urlencoded.

  https://beta-api.ambita.com/authentication/v2/token
  username=12000aUser&password=thePassword&grant_type=password&client_id=anClientId

If authentication is successful, a JSON will be returned:

Trusted grant

To obtain an access (and refresh) token you must call the token service POST /authentication/v2/token.

Required parameters are:

grant_type=trusted
client_id=<your id>
client_secret=<your client secret>
username=<user's logon ident>

The user must be registered in the Ambita Usercatalog. Example below is using MIME type application/x-www-form-urlencoded.

If authentication is successful, a JSON will be returned:

Refresh a token

When a token expires the client must choose between refreshing the token using the refresh_token or authenticating again as described above. Refreshing a token is pretty similar to authenticating. You don't need to send in client_id and client_secret for non-confidential clients. You post to the token service POST /authentication/v2/token but uses grant_type=refresh_token. For confidential clients the following parameters are required:

grant_type=refresh_token
client_id=<your id>
client_secret=<your secret>
refresh_token=<refresh_token>

For non-confidential clients the following parameters are required:

grant_type=refresh_token
refresh_token=<refresh_token>

Calling a service that demands an access token

When calling a service that requires an access token, the client must first obtain a token and then add the access token to the request header like this: