# auth.md

You are an agent. Astra MCP supports agent registration via OAuth 2.1 dynamic client registration (RFC 7591) and authorization code + PKCE. The resource server is `https://mcp.getastra.com`. The authorization server is `https://mcp-auth.getastra.com`.

This service does **not** implement Auth.md ID-JAG (`identity_assertion`), verified-email (`service_auth`), or anonymous claim ceremonies. Do not POST to `/agent/identity` or `/agent/auth`. Use DCR and the authorization-code flow below.

Users must already have an Astra account (email/password or SSO). New humans sign up at the dashboard, not through this protocol.

Signup: https://my.getastra.dev/signup

## 1. Discover

On `401` from the MCP transport, read `WWW-Authenticate` and fetch `resource_metadata`. If you do not have a 401, use the conventional PRM URL.

```http
GET https://mcp.getastra.com/.well-known/oauth-protected-resource
```

Read `resource` (MCP audience), `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`. Then fetch Authorization Server metadata from the advertised issuer:

```http
GET https://mcp-auth.getastra.com/.well-known/oauth-authorization-server
```

The MCP origin also serves this document at `/.well-known/oauth-authorization-server` for clients that probe the resource host. Token, register, and authorize URLs stay on the authorization server.

From AS metadata, read `issuer`, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `revocation_endpoint`, `grant_types_supported`, and `agent_auth`.

`agent_auth` fields:

- `skill` — this document (https://mcp.getastra.com/auth.md)
- `register_uri` — RFC 7591 DCR (https://mcp-auth.getastra.com/api/auth/oauth2/register)
- `revocation_uri` — RFC 7009 token revocation (https://mcp-auth.getastra.com/api/auth/oauth2/revoke)
- `identity_types_supported` — `oauth_dcr` only
- `oauth_dcr.credential_types_supported` — `access_token`

There is no `claim_uri`. Do not send ID-JAG or anonymous identity bodies.

## 2. Register an OAuth client (DCR)

POST RFC 7591 JSON to `agent_auth.register_uri`. Public native clients must use `token_endpoint_auth_method: "none"` and PKCE (`S256`).

```http
POST https://mcp-auth.getastra.com/api/auth/oauth2/register
Content-Type: application/json

{
  "client_name": "<your agent name>",
  "redirect_uris": ["<your loopback or claimed HTTPS redirect>"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}
```

Save `client_id` from the response. Do not send a client secret; this is a public client.

## 3. Authorize the user

Send the user through `authorization_endpoint` with:

- `response_type=code`
- `code_challenge` / `code_challenge_method=S256`
- `scope` from a subset of: openid, profile, email, offline_access
- `resource=https://mcp.getastra.com/mcp` (required so access tokens are audience-bound to MCP)
- `redirect_uri` matching registration

The user signs in on the authorization server (email/password or SSO) and consents. Exchange the code at `token_endpoint` with `grant_type=authorization_code` and `code_verifier`.

## 4. Call MCP

Present the access token as a header bearer credential:

```http
POST https://mcp.getastra.com/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
```

When the access token expires, use `grant_type=refresh_token`. If refresh fails, restart at step 3.

## 5. Revoke

POST the access token to `revocation_uri` (https://mcp-auth.getastra.com/api/auth/oauth2/revoke) per RFC 7009 when the user disconnects the agent. This service does not ingest Auth.md security-event tokens.

## Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 on `/mcp` with `resource_metadata` | Missing or invalid Bearer | Re-discover PRM and obtain a new token |
| 4xx on DCR | Invalid client metadata | Fix `redirect_uris` / `token_endpoint_auth_method` and retry |

Protected Resource Metadata is authoritative if it conflicts with this file.