# AwesomeFee auth.md

You are an agent. AwesomeFee sells TRON Energy and Bandwidth. There are two APIs and four ways in; pick the first that fits.

| You have | Use | API |
|---|---|---|
| a USDC wallet on Base, no account | x402, no registration (section 1) | `https://api.awesomefee.com` |
| only your user's email | auth.md `service_auth` (section 2) | `https://cabinet-api.awesomefee.com/api/v1` |
| a browser and a redirect URI (MCP client, app) | OAuth authorization code + PKCE (section 3) | `https://cabinet-api.awesomefee.com/api/v1` |
| an API key the user gave you | `X-API-Key` or `client_credentials` (section 4) | `https://cabinet-api.awesomefee.com/api/v1` |

## Discovery

- Protected Resource Metadata: `https://cabinet-api.awesomefee.com/.well-known/oauth-protected-resource` (also on https://awesomefee.com). A `401` from the
  business API carries `WWW-Authenticate: Bearer resource_metadata="…"` with this URL.
- Authorization Server Metadata: `https://cabinet-api.awesomefee.com/.well-known/oauth-authorization-server` (issuer `https://cabinet-api.awesomefee.com`, block `agent_auth`).
- Scopes: `read` (all GET: addresses, resources, orders, price), `write` (create orders, early reclaim). Tokens act for one
  organization: its ID (`org_…`) is the `org_id` claim of the access token and goes in the path, `/orgs/{orgId}/…`.

## 1. x402 — no registration (agent API)

- Call a paid route (`POST https://api.awesomefee.com/x402/v1/tron/energy` and others; catalogue: `GET https://api.awesomefee.com/v1/search`). The answer is `402`
  with the terms in `PAYMENT-REQUIRED`; sign a USDC authorization (EIP-3009) and repeat the same request with
  `PAYMENT-SIGNATURE`. `202` means accepted — do not pay again.
- Terms before paying: `GET https://api.awesomefee.com/x402/v1/quote?product=energy&amount=65000`.
- Docs: https://awesomefee.com/docs/en/agents/overview/ · https://api.awesomefee.com/llms.txt · https://api.awesomefee.com/openapi.json

## 2. service_auth — you know the user's email

1. Register: `POST https://cabinet-api.awesomefee.com/api/v1/agent/identity` with `{"type":"service_auth","login_hint":"<user email>"}`. The answer has
   `claim_token` (keep it in memory, it is returned once) and `claim` = `{user_code, verification_uri, expires_in, interval}`.
2. Tell the user, in one message: "Open <verification_uri>, sign in as <email> and enter the code **<user_code>**." The user
   signs in to the cabinet (or signs up), picks the organization and the scopes and types the code. The code goes into
   that page, not back to you.
3. Poll `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>`
   every `interval` seconds: `authorization_pending` → keep polling; `slow_down` → add 5 s; `expired_token` → get a new
   code with `POST https://cabinet-api.awesomefee.com/api/v1/agent/identity/claim` `{"claim_token":"…","email":"<user email>"}` (the registration lives
   24 h). Success: `access_token` (1 h) and `identity_assertion` (30 days).
4. When the access token expires: `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` with
   `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>`. `invalid_grant` → start again
   at step 1.

`anonymous` and ID-JAG registrations are not enabled (`anonymous_not_enabled`, `issuer_not_enabled`): without an account
use x402.

## 3. Authorization code + PKCE — MCP clients and apps

1. Register the client (RFC 7591): `POST https://cabinet-api.awesomefee.com/api/v1/oauth/register` with
   `{"client_name":"…","redirect_uris":["https://…/callback"]}` → `client_id`. Public clients only
   (`token_endpoint_auth_method: none`); http redirect URIs only on loopback.
2. Send the user to `https://cabinet-api.awesomefee.com/api/v1/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&scope=read%20write&state=…`.
   The user approves in the cabinet (https://app.awesomefee.com/en/app) and picks the organization.
3. Exchange the code: `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` with `grant_type=authorization_code&code=…&client_id=…&redirect_uri=…&code_verifier=…`
   → `access_token` (1 h) and `refresh_token` (30 days, rotated on each use: a reused refresh token revokes the grant).

## 4. API key — the user gave you one

- A person creates the key in the cabinet (https://app.awesomefee.com/en/app, "API keys"; the secret is shown once). The same screen shows the
  organization ID and the API address.
- Send `X-API-Key: <key>` on every request to `https://cabinet-api.awesomefee.com/api/v1`, or exchange it for a bearer token:
  `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` with `grant_type=client_credentials&client_secret=<key>` (optionally `client_id=<key id>`, `scope=read`).

## Use and revocation

- Send `Authorization: Bearer <access_token>` to `https://cabinet-api.awesomefee.com/api/v1/orgs/{orgId}/…`. Errors are `{"error","code"}`; `401` = get
  a new token, `403` = the scope does not allow it.
- A consent (section 3) or an agent claim (section 2) appears in the cabinet as an API key marked "agent"; revoking it there
  cuts every token of the grant. Tokens from `client_credentials` die with their key.
  An access or refresh token can be revoked with `POST https://cabinet-api.awesomefee.com/api/v1/oauth/revoke` (`token=…`, RFC 7009).
- Business API guide: https://awesomefee.com/docs/en/integration/api/
