> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Introspection

> Validate access tokens server-side using RFC 7662 token introspection.

HASP implements RFC 7662 token introspection. Your resource server can call the introspection endpoint to check whether an access token is active and retrieve its metadata without needing to parse or verify a JWT.

## Endpoint

```
POST /v1/oauth/introspect
```

## Request

```bash theme={null}
curl -X POST https://api.usehasp.com/v1/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "hasp_app_01J...:hasp_cs_live_..." \
  -d "token=hasp_agt_live_..."
```

Authenticate using HTTP Basic with your `client_id` as the username and `client_secret` as the password.

## Response — active token

```json theme={null}
{
  "active": true,
  "sub": "01JQUSER000000000000000000",
  "client_id": "hasp_app_01J...",
  "iat": 1716000000,
  "exp": 1716028800,
  "scope": "hasp.data.read hasp.data.write",
  "authorization_details": [
    { "type": "hasp.data.read" },
    { "type": "hasp.data.write" }
  ]
}
```

The `sub` field is the delegating user's ID (the human who authorized the token), not an agent identifier.

## Response — inactive token

```json theme={null}
{ "active": false }
```

Inactive tokens include: unknown tokens, expired tokens, revoked tokens, and tokens issued by a different application.

## Testing in the developer console

From your application's detail page (Overview tab), use the **Test introspection** panel. Paste a `hasp_agt_` token and click **Test token** to see the introspection response live. This calls a server-side proxy that authenticates with your application's credentials automatically — no manual auth setup needed.

## Caching considerations

Introspection results may be cached for a short period. For latency-sensitive paths, cache the `{ active, exp, authorization_details }` tuple until `exp - 60s` so you make at most one introspection call per token per request session.

Do not cache `active: false` responses for more than a few seconds — a token may become inactive between your cache entry and the next use.