> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/how-it-works/agent-key-exchange.md).

# Agent Key Exchange

Agent API keys are exchange-only credentials. A `brain_ak_*` key is never sent to resource routes. The agent exchanges it for a five-minute JWT and uses that JWT to call `POST /v1/authorizations`.

## Discover Metadata

```http
GET /v1/auth/agent-key-exchange
```

Response:

```json
{
  "issuer": "https://staging-auth.robotmoney.com",
  "exchange": {
    "token_endpoint": "https://staging-auth.robotmoney.com/token",
    "resource": "https://staging-api.robotmoney.com/",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:brain:params:oauth:token-type:agent-api-key",
    "scope": "payment_intent:propose",
    "key_display": "once"
  }
}
```

Always use the discovered `resource` value. It is the token audience for the API and is not necessarily the same host as the public API base.

## Exchange

```bash
curl -sS -X POST "$TOKEN_ENDPOINT" \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=$AGENT_KEY" \
  --data-urlencode "subject_token_type=urn:brain:params:oauth:token-type:agent-api-key" \
  --data-urlencode "resource=$API_RESOURCE" \
  --data-urlencode "scope=payment_intent:propose"
```

Response:

```json
{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "payment_intent:propose"
}
```

The exchange response never includes a refresh token. Exchange the agent key again when a fresh JWT is needed.

## Values

| Value          | Staging                                     | Production                      |
| -------------- | ------------------------------------------- | ------------------------------- |
| API base       | `https://staging-api.robotmoney.com/v1`     | `https://api.robotmoney.com/v1` |
| Auth issuer    | `https://staging-auth.robotmoney.com`       | `https://auth.brain.fi`         |
| Token endpoint | `https://staging-auth.robotmoney.com/token` | `https://auth.brain.fi/token`   |
| API resource   | `https://staging-api.robotmoney.com/`       | `https://api.brain.fi/`         |