# Auth.md — Bonds API agent registration

Bonds API supports two equivalent ways for an agent to authenticate.
Both resolve to the same account and the same underlying credential
(your API key) — OAuth is offered as an alternate, standards-based
front door for agents that already speak OAuth.

## 1. API key (simplest)

Register at https://bonds-api.com/register, then create a key at
https://bonds-api.com/dashboard/api-keys. Send it as the `X-API-Key`
header on every request.

## 2. OAuth 2.0 client_credentials

- Discovery: `GET /.well-known/oauth-authorization-server`
- Protected resource metadata: `GET /.well-known/oauth-protected-resource`
- Token endpoint: `POST /oauth/token`
  (`grant_type=client_credentials`, `client_id`, `client_secret`)
- `client_id` is shown in the dashboard next to each API key;
  `client_secret` is the key itself.
- Returns a bearer token (1 hour TTL). Send it as
  `Authorization: Bearer <token>` instead of `X-API-Key`.

## Registration

- register_uri: https://bonds-api.com/register
- identity assertion: verified_email (Bonds API requires email
  verification on sign-up before an account can create API keys)
- credential types supported: api_key, oauth2_client_credentials
- claim / manage credentials: https://bonds-api.com/dashboard/api-keys
- revoke a credential: deactivate the key at
  https://bonds-api.com/dashboard/api-keys (revokes both the API key and
  any bearer tokens issued from it)

## Rate limits & plans

See https://bonds-api.com/docs for plan tiers, quotas, and a free 7-day
trial. A limited no-key sandbox is available via `docs_test=1` on any
endpoint.