POST /auth/token

Exchange the Authorization Code for an Access Token

The token endpoint will validate all request parameters, confirming that the code is still valid and that the client ID and client secret are correct. Once everything is verified, it will generate and return an access token. The application will then have an access token available for making Unity API requests.

Request Information

As defined in the OAuth 2.0 protocol, the token request needs to be formatted as application/x-www-form-urlencoded.

Resource Description

NameDescriptionTypeAdditional information
client_id

The unique identifier assigned to your application.

 string

Required. Use HTTP Basic Authentication as stated in the Note section below.
client_secret

The password for your application.

 string

Required. Use HTTP Basic Authentication as stated in the Note section below.
code

The authorization code received from Unity AuthServer.

 string

Required. To validate and exchange with Unity API access token.

grant_type

MUST be set to "authorization_code".

 string

Required.
scope

Specifies the set of operations the requested access token should be permitted to use. When requesting multiple scopes, the value must be expressed as a list of space-delimited API scopes.

 string

Required. See Service Extensions and Scopes for further details.

Note

It is recommended to use the HTTP Basic Authentication scheme (as defined in RFC 2617) for client authentication. Only clients unable to directly utilize the HTTP Basic Authentication should send "client_id" and "client_secret" in the request body. In order for a client to use HTTP Basic Authentication, the following steps need to be performed:

  • Concatenate "client_id" and "client_secret" with a colon in between: {client_id}:{client_secret}
  • Base64-encode the concatenated string.
  • Add the following Authorization header to the request: Basic {Base64-encoded-string}

Request Format (with HTTP Basic Authentication)

POST /auth/token HTTP/1.1
Authorization: Basic bXlUZXN0QXBwOm15U2VjcmV0
Content-Type: application/x-www-form-urlencoded

code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback&scope=Console.GSM+SkyStatus.Reporting

Request Format (with "client_id" and "client_secret" in request body)

POST /auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=myTestApp&client_secret=mySecret&code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback&scope=Console.GSM+SkyStatus.Reporting

Response Information

As defined in the OAuth 2.0 protocol, the token response is formatted as JSON.

Resource Description

NameDescriptionTypeAdditional information
access_token

The access token used to send authenticated requests to the Unity API.

 string

Required
token_type

Identifies the type of token. This field is always set to "bearer".

 string

Required
expires_in

The lifetime of the access token in seconds.

 number

Required
refresh_token

The refresh token used for refreshing (obtaining a new) access token.

 string

Required
scope

The set of operations the issued access token is permitted to request.

 string

Required

Response Format

{
    "access_token": "h9uAtymEyHDKRZex-CAdGGm7ckdv68vcsJtRNikQBKQKahPAVih2UHA0Kh8YxqjcK9WjKo8pQSXLT2KzBkL1yRzmvgzT3I3YOVl9vgHGjnZ3oGY87BJOb5SFYVx
                     PcUU33jPV--crrvi8BuSfBa3SptRhCzF1xDKTayQrTmg-zyliKofR2FvyrBUgS0SYt8RdOnOwcczhA_AaOBUgDCKTbgRTAs8Jnh7seBrbNMN4SWHbsLn1pMOE0bkoYz-mZhc8dqoJ_q
                     85yHmV8hLj00DE1DthL5SD0Ji79yCcLNOVDFdIU8Fm5WeQG-WtbptWrwkNyJDCBuvKtb3Iw2Ss3Qw1N0CQiLre0BgwbyTS0L7bKmd1MZDQ",
    "token_type": "bearer",
    "expires_in": 299,
    "refresh_token": "342187561f1943309d459ae2de05ecef",
    "scope": "[\"Console.GSM\",\"SkyStatus.Reporting\"]"
}