# auth.md

FreightPulse 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://freightpulsehq.com/.well-known/oauth-protected-resource
2. Fetch Authorization Server metadata (includes the `agent_auth` block): https://freightpulsehq.com/.well-known/oauth-authorization-server
3. Register at `agent_auth.register_uri`, then exchange client credentials at the `token_endpoint`

## Agent self-registration (anonymous)

**Registration endpoint (`register_uri`):** `POST https://freightpulsehq.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 on FreightPulse's perpetual free tier (100 requests/month) - not a placeholder and not a time-boxed trial.

### Step 1 - Register a client

```
curl -X POST https://freightpulsehq.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://freightpulsehq.com/oauth/token", ... }
```

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

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

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

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

```
curl https://freightpulsehq.com/api/v1/fuel-prices \
  -H "Authorization: Bearer fp_live_..."
```

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 free-tier accounts are not bound to a human user, and a compromised credential is retired by re-registering.

**Caveats:**
- Fixed free-tier quota: 100 requests/month, 5 requests/minute
- `contact_email` is not verified - it's used only for abuse contact
- ID-JAG / verified-email identity assertions are not accepted
- For higher quotas, use human signup below instead

## Human signup (paid plans)

1. Create an account: https://freightpulsehq.com/register
2. Generate an API key from the dashboard: https://freightpulsehq.com/dashboard (a free key works immediately - no credit card required for the free tier)
3. Subscribe to a paid plan for a higher quota/rate limit: https://freightpulsehq.com/dashboard/billing
4. Send the key on every request via the `X-API-Key` header (an `Authorization: Bearer <key>` header also works)

## No API key at all? Guest access

Every `/api/v1/*` endpoint also accepts unauthenticated requests, capped at 100 requests/day per IP: no registration needed for a quick lookup.

## Base URL

```
https://freightpulsehq.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://freightpulsehq.com/docs
- Terms: https://freightpulsehq.com/terms
- Privacy: https://freightpulsehq.com/privacy