# POST /oauth/token

> Request an access token with the authorization_code, client_credentials or refresh_token grant as form data; get a Bearer token valid for 3600 seconds.

- **Product:** DS Server
- **Section:** Documentation
- **Kind:** Endpoint
- **Path:** DS Server > API Reference > Web API > OAuth > /token > POST /oauth/token
- **1989 words**
- **Web URL:** https://docs.textcontrol.com/ds-server/reference/web-api/oauth/token/post/
- **LLMs URL:** https://docs.textcontrol.com/ds-server/reference/web-api/oauth/token/post/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/ds-server/reference/web-api/oauth/token/post/llms-full.txt

---

`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](https://docs.textcontrol.com/ds-server/reference/web-api/authenticationserver/token/post/llms-full.txt)) 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.

```bash
# 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](https://docs.textcontrol.com/ds-server/reference/web-api/oauth/authorize/get/llms-full.txt) 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.

```bash
# 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.

```bash
# 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

| Header field | Description |
|---|---|
| Authorization | The client ID and the client secret of the security profile are combined into a string separated by a colon, e.g.: clientid:clientsecret. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space i.e. "Basic " is then put before the encoded string. For example: `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l` |

### Request Payload

| Type | Value |
|---|---|
| TokenData | The parameters of the TokenData object must be sent using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request body payload. A request without form data, for example with a JSON body, is rejected with 405 (Method Not Allowed). |

#### TokenData

| Name | Type | Value | Optional |
|---|---|---|---|
| grant\_type | String | The grant type of the token request. Supported values are "authorization\_code", "client\_credentials" and "refresh\_token". | no |
| code | String | The authorization code returned by GET /oauth/authorize. Required for the "authorization\_code" grant type. A code can be exchanged only once. | yes |
| redirect\_uri | String | The redirect URI the authorization code was requested with. It must match one of the authorized redirect URIs of the security profile; upper and lower case are ignored. Required for the "authorization\_code" grant type. | yes |
| client\_id | String | The client ID of the security profile. Required for the "authorization\_code" grant type; for "client\_credentials", it is sent in the Basic authorization header. | yes |
| client\_secret | String | The client secret of the security profile. Required for the "authorization\_code" grant type; for "client\_credentials", it is sent in the Basic authorization header. | yes |
| refresh\_token | String | The refresh token of a previous response. Required for the "refresh\_token" grant type. A refresh token can be used only once. | yes |
| scope | String | The scope of the request. | yes |

### Success Response

| Status | Description |
|---|---|
| 200 | On success, the HTTP status code in the response header is 200 (OK). It returns a JSON object (`application/json`) with `access_token`, `token_type` ("Bearer") and `expires_in` (the lifetime in seconds as a string, "3600"). The "authorization\_code" and "refresh\_token" grant types also return a new `refresh_token`. |

### Error Response

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

| Status | Description |
|---|---|
| 400 | `invalid_request` "Missing authorization header." is returned, if the "client\_credentials" grant type is requested without a Basic authorization header. A Basic authorization header that can't be decoded or has no colon returns `invalid_request` with a description of the problem, and another authorization type returns "Unexpected authorization type. (Bearer)". |
| 400 | `invalid_request` "Missing 'client\_id' parameter.", "Missing 'code' parameter." or "Missing 'redirect\_uri' parameter." is returned, if a form field required by the "authorization\_code" grant type is missing, and "Missing 'refresh\_token' parameter.", if the "refresh\_token" grant type has no refresh token. |
| 400 | `invalid_client` "Invalid client ID." or "Invalid client secret." is returned, if the client credentials don't match a security profile. |
| 400 | `unsupported_grant_type` "This security profile does not allow the specified grant type. (client\_credentials)" is returned, if the grant type is not supported or not allowed for the security profile. The grant type that was sent is given in parentheses. |
| 400 | `invalid_grant` "Invalid authorization code." is returned, if the authorization code is not valid, was already used or was requested with another redirect URI. |
| 400 | `invalid_grant` "Invalid refresh token." is returned, if the refresh token is not valid or was already used. |
| 405 | A 405 (Method Not Allowed) with a problem details object (`application/problem+json`) is returned, if the body is not form data. |

---

## Nearby

- **Previous:** [/oauth/token](https://docs.textcontrol.com/ds-server/reference/web-api/oauth/token/llms-full.txt)
- **Next:** [/oauth/validatetoken](https://docs.textcontrol.com/ds-server/reference/web-api/oauth/validatetoken/llms-full.txt)