# auth.md

> Agent registration and authentication for HoneyCoin APIs.
> Last updated: 2026-07-20

HoneyCoin does **not** currently expose a public OAuth/OIDC authorization server for agent self-registration. Agents authenticate with **API keys** issued from the B2B dashboard, then exchange them for short-lived **Bearer tokens**.

This file is the canonical discovery document for how AI agents and automated systems obtain and use credentials.

## Audience

- AI agents automating payouts, collections, FX, on/off-ramps, or reconciliation
- Developers embedding HoneyCoin payment rails into products or workflows
- Internal automation bots with approved API access

## Registration (get credentials)

There is no automated `POST /agent/auth` self-registration endpoint yet. Provision access as follows:

1. **Create a business account:** [https://b2b.honeycoin.app/register](https://b2b.honeycoin.app/register)
2. **Complete onboarding / KYB** as required in the dashboard
3. **Create API keys:** Dashboard → **Developers → API Keys**
4. Copy:
   - **API Key** (format: `HC_…`)
   - **Public Key**

For enterprise / agent-network access, contact **api@honeycoin.app** or **sales@honeycoin.app**.

## Supported authentication method

| Method | Status |
|--------|--------|
| API Key + Public Key → Bearer JWT | Supported (production) |
| OAuth 2.0 / OIDC agent registration | Not available |
| Anonymous agent claim flows | Not available |

### Step 1 — Generate a Bearer token

```http
POST https://api-v2.honeycoin.app/api/b2b/auth/generate-bearer-token
Content-Type: application/json
api-key: YOUR_API_KEY

{"publicKey": "YOUR_PUBLIC_KEY"}
```

Example response:

```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....",
  "expiresAt": 1752085041
}
```

### Step 2 — Call APIs with the Bearer token

```http
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json
```

**Token lifetime:** ~2 hours. Agents must refresh tokens before expiry.

Sandbox token generation uses the same path under:

`https://api-v2.honeycoin.app/api/sandbox/b2b/auth/generate-bearer-token`

## API bases

| Environment | Base URL |
|-------------|----------|
| Production (B2B / Fiat) | `https://api-v2.honeycoin.app/api/b2b` |
| Sandbox (B2B / Fiat) | `https://api-v2.honeycoin.app/api/sandbox/b2b` |
| Production (Crypto) | `https://crypto.honeycoin.app/api` |
| Sandbox (Crypto) | `https://crypto.honeycoin.app/api/sandbox` |

## Machine-readable discovery

- Agent capabilities: https://honeycoin.app/agents.md
- API catalog (RFC 9727): https://honeycoin.app/.well-known/api-catalog
- MCP Server Card: https://honeycoin.app/.well-known/mcp/server-card.json
- OAuth Protected Resource (RFC 9728): https://honeycoin.app/.well-known/oauth-protected-resource
- OpenAPI (B2B): https://honeycoin.app/openapi/b2b.json
- OpenAPI (Crypto): https://honeycoin.app/openapi/crypto.json
- Human docs: https://docs.honeycoin.app
- LLM site index: https://honeycoin.app/llms.txt

**Note:** HoneyCoin does not publish OAuth/OIDC Authorization Server metadata. Agents obtain Bearer tokens via API Key + Public Key as documented above. The Protected Resource document describes Bearer header usage for the B2B API resource.
## Credential use rules

- Store API keys and public keys as secrets; never embed them in public agent prompts or client-side code
- Prefer sandbox credentials while testing
- Rotate keys from the dashboard if compromised
- Use unique `externalReference` values per transaction
- Respect webhook timeouts (15s) and idempotency expectations documented at https://docs.honeycoin.app

## Contact

- API access / technical: api@honeycoin.app
- Sales / partnerships: sales@honeycoin.app
- Dashboard: https://b2b.honeycoin.app