Token

Description	Method for retrieving a new OAuth2 access token.
Path	oauth/token
Since (API version)	3.0

This endpoint can be used for retrieving new tokens.

To be able to access this endpoint he client must authenticate himself.

Sending a POST request to the oauth/token endpoint will return a new access token, and depending on the client configuration, it might also return a new refresh token.

Example request:

POST /https/api/rest/v3.0/oauth/token

{
   grant_type="refresh_token"
   scope="mail"
   client_id="MyClient"
   client_secret="abcd1234"
   refresh_token="72361905e14ee14ecb91c4eff85416e8fa69199e"
}

Example response:

{
   "access_token": "761eb1476c4754974a467180a84338a385ebbc68",
   "token_type": "Bearer",
   "expires_in": 3600,
   "refresh_token": "d9528d345dccf4e350a95a3fa3de490cbfb9b4fc"
}

All attributes that could be included in the request are explained in the table below.

Property	Description
grant_type	REQUIRED. There are several ways to request a new access token. This attribute value tells which request flow to use. The value could be "refresh_token", "client_credentials", "password" or "authorization_code".
code	If authorization_code grant is used, this attribute is REQUIRED, otherwise IGNORED. The code has been retrieved in a previous request towards the authorize endpoint.
redirect_uri	If authorization_code grant is used, this attribute is REQUIRED -if- the redirect_uri parameter was included in the previous request towards the authorize endpoint (the request from where the code was retrieved). For other grant types, this attribute is IGNORED.
scope	REQUIRED. In this implementation there is no default scope specified, therefore the scope attribute is mandatory. One or more scopes can be defined.
refresh_token	If refresh_token grant is used, this attribute is REQUIRED, otherwise IGNORED. This is the value of the refresh token being used to request a new access token. The refresh token will be revoked, and a new refresh token will be returned together with the new access token.
username	If password grant flow is used, this attribute is REQUIRED, otherwise IGNORED. This is the name of the resource owner.
password	If password grant flow is used, this attribute is REQUIRED, otherwise IGNORED. This is the resource owner's password.
client_id	Client id used for authentication. If no Basic Authorization header or Client Certificate is sent in the request, this attribute is REQUIRED, otherwise IGNORED.
client_secret	Client secret used for authentication. If no Basic Authorization header or Client Certificate is sent in the request, this attribute is REQUIRED, otherwise IGNORED.

Error responses

Several validations are performed before possibly issuing new token(s). Examples of some, but not all, error responses that can be returned are listed below.

If refresh_token grant flow is used and the refresh token has expired:

{
    "error": "INVALID_GRANT",
    "errorDescription": "Refresh token expired."
}

If authorization_code grant flow is used and the code is invalid:

{
    "error": "INVALID_GRANT",
    "errorDescription": "invalid authorization code."
}

If the scope attribute is omitted, or if the validation of the scope(s) failed:

{
    "error": "INVALID_SCOPE",
    "errorDescription": "Invalid scope"
}

RFC

The token endpoint is according to the RFC 6749 standard, "The OAuth 2.0 Authorization Framework". For more details see: http://tools.ietf.org/html/rfc6749