# auth.md

BankDataStack issues scoped API credentials to agents without a sign-up form.

**Audience:** AI agents and other autonomous clients that need a working credential without a human filling out a form or entering a credit card.

**Supported identity type:** `anonymous` (no user identity assertion; no claim ceremony).

**Credential types issued:** `access_token` (OAuth Bearer) and `api_key` (same secret, also accepted as `X-API-Key`).

## Discovery

1. Fetch Protected Resource Metadata: https://www.bankdatastack.com/.well-known/oauth-protected-resource
2. Fetch Authorization Server metadata (includes the `agent_auth` block): https://www.bankdatastack.com/.well-known/oauth-authorization-server
3. Register at `agent_auth.register_uri`, then exchange client credentials at the `token_endpoint`

Unauthenticated API calls also return `WWW-Authenticate: Bearer resource_metadata="https://www.bankdatastack.com/.well-known/oauth-protected-resource"`.

## Agent self-registration (anonymous)

**Registration endpoint (`register_uri`):** `POST https://www.bankdatastack.com/oauth/register`

**Supported method:** anonymous registration followed by OAuth 2.0 Client Credentials Grant (RFC 6749 §4.4). This issues a real, working credential — not a placeholder.

### Step 1 — Register a client

```
curl -X POST https://www.bankdatastack.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "my-agent", "contact_email": "you@example.com"}'
```

Response (`201`):
```
{ "client_id": "...", "client_secret": "...", "token_endpoint": "https://www.bankdatastack.com/oauth/token", ... }
```

### Step 2 — Exchange the client credentials for an access token

```
curl -X POST https://www.bankdatastack.com/oauth/token \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
```

Response (`200`):
```
{ "access_token": "bds_...", "token_type": "Bearer", "expires_in": 604800, "scope": "api" }
```

### Step 3 — Call the API with the credential

```
curl https://www.bankdatastack.com/api/v1/routing/validate?routing_number=021000021 \
  -H "Authorization: Bearer bds_..."
```

The `access_token` is a bearer credential. Send it as `Authorization: Bearer <access_token>` on every API request (an `X-API-Key` header with the same value also works). It authenticates the agent-issued account directly; it is not exchanged, refreshed, or wrapped in any further step.

There is no claim or revocation URL for this flow: anonymous sandbox accounts are not bound to a human user, and a compromised credential is retired by re-registering.

**Caveats — this is a sandbox credential, not a production one:**
- Fixed quota: 200 requests/month
- Fixed rate limit: 5 requests/minute
- The underlying account expires 7 days after registration; `/oauth/token` stops issuing new tokens once it has
- `contact_email` is not verified — it's used only for abuse contact
- ID-JAG / verified-email identity assertions are not accepted
- For anything beyond evaluation/testing, use human signup below instead

## Human signup (production-scale access)

1. Create an account: https://www.bankdatastack.com/register
2. Subscribe to a plan (7-day free trial, credit card required): https://www.bankdatastack.com/billing
3. Generate an API key from the dashboard: https://www.bankdatastack.com/dashboard
4. Send the key on every request via the `X-API-Key` header (an `Authorization: Bearer <key>` header also works)

## Base URL

```
https://www.bankdatastack.com/api/v1
```

## Notes

- Keys are scoped to a single account and its rate limit / monthly quota.
- If a human-issued key is compromised, revoke and regenerate it from the dashboard immediately.
- Full endpoint reference: https://www.bankdatastack.com/docs
- Terms: https://www.bankdatastack.com/terms
- Privacy: https://www.bankdatastack.com/privacy