# Token introspection endpoint

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

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.

Provides information about a token's current state and metadata.
Used by resource servers to validate tokens and get additional information.

Note: This endpoint requires client authentication to prevent token scanning attacks.

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

- `token` (string, required): The string value of the token to introspect
- `token_type_hint` (string): Optional hint about the type of token being introspected One of: `access_token`, `refresh_token`.
- `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.

## Responses

### 200: Token introspection response

```json
{
  "active": true,
  "application": "string",
  "exp": 0,
  "iat": 0,
  "username": "string"
}
```

### 400: Invalid request

### 401: Invalid client credentials

## Example request

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

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