# Token endpoint

`POST https://merchant.shuttleglobal.com/token`

Authenticate your client in one of two ways:
1. In the request body, with the `client_id` and `client_secret` parameters, or
2. With HTTP Basic authentication, using your `client_id` as the username and your `client_secret` as the password

Use one method per request, not both. If you put `client_id` or `client_secret` in the body, put both there.

This endpoint supports two use cases:

1. Authorization Code Exchange:
   - Use this when you have received an authorization code from the /authorize flow
   - Required parameters: grant_type=authorization_code, code, redirect_uri, plus your client credentials (see above)
   - Returns both access_token and refresh_token
   - The redirect_uri must match the one used in the original /authorize request
   - The authorization code must be exchanged within 15 minutes of being generated

2. Refresh Token Exchange:
   - Use this to get a new access_token when your current one expires
   - Required parameters: grant_type=refresh_token, refresh_token, plus your client credentials (see above)
   - Returns only access_token (refresh_token remains the same)
   - No redirect_uri needed for this flow

Notes:
- Access tokens expire after 1 hour (3600 seconds)
- Always store refresh_tokens securely - they are long-lived credentials
- If a refresh_token becomes compromised, obtain a new authorization code through the /authorize flow

## Authentication

- clientAuth: Basic Authentication using client credentials (RFC 7617) Used to authenticate clients to the OAuth server endpoints (/token, /revoke, /introspect). The client must Base64 encode their client_id and client_secret in the format: Authorization: Basic Base64(client_id:client_secret) Example: If client_id is '1234_5678' and client_secret is 'your_client_secret': Authorization: Basic MTIzNF81Njc4OnlvdXJfY2xpZW50X3NlY3JldA==

## Request body (`application/x-www-form-urlencoded`), required

- `client_id` (string): Your client ID. Required unless you send it with HTTP Basic authentication.
- `client_secret` (string): Your client secret. Required unless you send it with HTTP Basic authentication.
- `code` (string): Required for authorization_code grant
- `grant_type` (string, required) One of: `authorization_code`, `refresh_token`.
- `redirect_uri` (string (uri)): Required for authorization_code grant
- `refresh_token` (string): Required for refresh_token grant

## Responses

### 200: Token response

```json
{
  "access_token": "string",
  "expires_in": 3600,
  "refresh_token": "string",
  "token_type": "Bearer"
}
```

## Example request

```sh
curl --request POST \
  --url https://merchant.shuttleglobal.com/token \
  --header 'Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>' \
  --header 'Content-Type: application/json' \
  --data '{
  "grant_type": "authorization_code"
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/oauth/operations/gettoken/