POST /oauth/token

POST https://example.com/oauth/token

Description

The token endpoint is used to programmatically request access tokens. It supports the "authorization_code", "client_credentials" and "refresh_token" grant types. The "client_credentials" grant type works only for a security profile that allows it in the admin portal.

An access token is valid for 3600 seconds. The token is also issued for a security profile whose expiry date has passed, but the endpoints then reject it with 401 (Unauthorized).

When DS Server can't authorize the request itself, for example because it doesn't know the client ID, it forwards the request to the registered authentication servers (see POST /authenticationserver/token) and returns their answer.

Examples

This sample requests an access token with the "client_credentials" grant type. The client ID and client secret are sent in a Basic authorization header.

# Request:
curl --request POST 'https://trial.dsserver.io/oauth/token' \
    --user 'yourclientid:yourclientsecret' \
    --data-urlencode 'grant_type=client_credentials'

# Response:
{
    "access_token": "nmZ80Zn2R0P2AbS149E31IUHd5aZgB9T",
    "token_type": "Bearer",
    "expires_in": "3600"
}

This sample exchanges an authorization code returned by GET /oauth/authorize for an access token. The client ID and client secret are sent as form fields, and the redirect URI must be the one the code was requested with. An authorization code can be exchanged only once. The response also contains a refresh token.

# Request:
curl --request POST 'https://trial.dsserver.io/oauth/token' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3' \
    --data-urlencode 'client_id=yourclientid' \
    --data-urlencode 'client_secret=yourclientsecret' \
    --data-urlencode 'redirect_uri=https://localhost:5001/callback'

# Response:
{
    "access_token": "nmZ80Zn2R0P2AbS149E31IUHd5aZgB9T",
    "token_type": "Bearer",
    "expires_in": "3600",
    "refresh_token": "Ghk7w2LmNq0ZpX4rT8sV1uY6aB3cD9eF"
}

This sample requests a new access token with the refresh token of a previous response. The response contains a new access token and a new refresh token; the refresh token that was sent can't be used again.

# Request:
curl --request POST 'https://trial.dsserver.io/oauth/token' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'refresh_token=Ghk7w2LmNq0ZpX4rT8sV1uY6aB3cD9eF' \
    --data-urlencode 'client_id=yourclientid' \
    --data-urlencode 'client_secret=yourclientsecret'

Authorization

The "client_credentials" grant type requires the Basic authorization method. For the "authorization_code" grant type, the client ID and client secret are sent as the form fields client_id and client_secret instead; a Basic authorization header is not used for this grant type.

Basic

Request Payload

TokenData

Success Response

Error Response

The 400 errors return a JSON object (application/json) with the fields error and error_description.