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

# Discovery & Metadata

> Programmatically discover HASP's OAuth 2.1 endpoints, the MCP server metadata, and the authorization_details JSON Schema.

HASP publishes machine-readable discovery documents so clients can configure themselves without hard-coding endpoint URLs. All three documents below are public — no authentication is required — and are cached for five minutes (`Cache-Control: public, max-age=300`).

## Authorization server metadata (RFC 8414)

```
GET /.well-known/oauth-authorization-server
```

The RFC 8414 discovery document. Use it to locate every OAuth endpoint and the capabilities HASP supports, rather than constructing URLs yourself.

```json theme={null}
{
  "issuer": "https://api.usehasp.com",
  "authorization_endpoint": "https://api.usehasp.com/v1/oauth/authorize",
  "token_endpoint": "https://api.usehasp.com/v1/oauth/token",
  "device_authorization_endpoint": "https://api.usehasp.com/v1/oauth/device_authorization",
  "revocation_endpoint": "https://api.usehasp.com/v1/oauth/revoke",
  "introspection_endpoint": "https://api.usehasp.com/v1/oauth/introspect",
  "introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "urn:ietf:params:oauth:grant-type:device_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "authorization_details_types_supported": ["…"],
  "authorization_details_schema_uri": "https://api.usehasp.com/v1/schemas/authorization_details"
}
```

`authorization_details_types_supported` carries every RAR grant type the server
accepts. It is elided above rather than reproduced, because a copy in prose goes
stale the moment a type is added — read it from the live document, or see the
generated table under [authorization\_details JSON Schema](#authorization_details-json-schema)
below.

The `device_authorization_endpoint` and the `urn:ietf:params:oauth:grant-type:device_code` grant support the headless/SSH login flow — see [Device authorization](/platform/oauth/device-authorization).

<Note>PKCE is mandatory — `code_challenge_methods_supported` is `["S256"]` only, and `response_types_supported` is `["code"]`. There is no implicit grant. See [PKCE](/platform/oauth/pkce).</Note>

## MCP server metadata

```
GET /.well-known/mcp-server
```

Declares HASP as an MCP-authorized resource server supporting OAuth 2.1 with Rich Authorization Requests (RAR). MCP clients read this to set up the authorization handshake.

```json theme={null}
{
  "mcp_version": "2025-11-05",
  "resource_server": "https://api.usehasp.com",
  "authorization": {
    "type": "oauth2",
    "oauth_metadata_uri": "https://api.usehasp.com/.well-known/oauth-authorization-server",
    "grant_types_supported": ["authorization_code"],
    "code_challenge_methods_supported": ["S256"],
    "token_format": "opaque"
  },
  "capabilities": {
    "tool_authorization": true,
    "rich_authorization_requests": true
  }
}
```

The `mcp_version` field tracks the MCP authorization spec version HASP currently implements. Tokens are opaque (`token_format: "opaque"`) — validate them with [token introspection](/platform/oauth/introspection) rather than parsing them.

## authorization\_details JSON Schema

```
GET /v1/schemas/authorization_details
```

Returns the canonical JSON Schema (draft 2020-12) for the RAR `authorization_details` array — the same schema the in-console scope-grant builder validates against. Fetch it to validate `authorization_details` client-side before requesting a credential.

The response supports conditional requests: it returns an `ETag` and honors `If-None-Match`, replying `304 Not Modified` when your cached copy is current.

```bash theme={null}
curl https://api.usehasp.com/v1/schemas/authorization_details
```

The schema's top level is an array of one-or-more grant objects, each matching one of the supported `authorization_details` types:

| Type                   | Description                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `hasp.data.read`       | Read records from an app, optionally narrowed to specific entities, fields, and filters.                 |
| `hasp.data.write`      | Write records to an app, optionally narrowed to specific entities and fields.                            |
| `external.tool.invoke` | Invoke one named external tool. One grant per tool.                                                      |
| `tool.destructive`     | Invoke one named destructive capability. Wildcards are rejected — the tool must be named.                |
| `agent.delegate`       | Delegate authority to another agent, bounded by `max_chain_depth` (1–10).                                |
| `agent.compose`        | Compose with another agent by `agent_id`.                                                                |
| `human.escalate`       | Escalate to a human — exactly one of `to_role` or `to_user_id`.                                          |
| `workflow.schedule`    | Create scheduled runs for named workflows, bounded by horizon, interval, live-schedule count, and depth. |
| `workflow.invoke`      | Invoke named workflows over A2A. The wildcard `*` is permitted only as the sole element.                 |

See [Scope grants](/ai-api/agents/scope-grants) for each type's required fields, and the [consent screen](/platform/oauth/consent-screen) for how a requested grant is presented to the approving user.

## Token revocation (RFC 7009)

```
POST /v1/oauth/revoke
```

Revoke an agent credential by presenting it. Authenticate by sending the token itself as a bearer token — the caller proves possession.

```bash theme={null}
curl -X POST https://api.usehasp.com/v1/oauth/revoke \
  -H "Authorization: Bearer hasp_agt_live_..."
```

Per RFC 7009 §2.2 the endpoint always returns `200` with an empty body `{}`, even for an unknown or already-revoked token. Revocation is immediate: the credential cannot be used on any surface after the call returns.