# auth.md You are an agent. This file explains how to get access to AudD's music recognition API: sign up and pay for prepaid requests yourself (no AudD account and no email needed), or use the credentials of a user who has an AudD account. ## Agents: sign up, pay, recognize AudD supports auth.md's `anonymous` registration. One request returns an API key. You buy prepaid requests with a machine payment (HTTP 402, MPP), then call the recognition endpoint with the key. - Recognition endpoint: `POST https://api.audd.io/agent/recognize` - Protected resource metadata (RFC 9728): https://api.audd.io/.well-known/oauth-protected-resource/agent/recognize - Service document (JSON: endpoints, live price, pack size, limits, charge rule): https://dashboard-api.audd.io/agent/ - A request to the recognition endpoint without a key answers `401` with `WWW-Authenticate: Bearer` and `Link: ; rel="help"`. Its body names the registration and purchase endpoints. Buying spends real money. Pay only with a payment method, and up to an amount, that your user has authorized. ### 1. Register ```http POST https://dashboard-api.audd.io/agent/identity Content-Type: application/json {"type": "anonymous"} ``` Optional fields: `client_name` and `agent_platform` (each at most 40 printable characters) and `contact_email` (stored unverified; for receipts and notices). Other auth.md registration types (`identity_assertion`, `service_auth`) and the claim ceremony are not offered. The response carries `registration_id`, `refresh_token` (`audd_art_...`) and `audd.api_key` (`agt_...`). Store both as secrets: the key is shown once. Registration is free and includes no free requests; the balance starts at 0. The response also contains an `identity_assertion`. Token exchange is not offered yet: use `audd.api_key` as your credential. ### 2. Buy prepaid requests Requests come in packs of 1,000, 1 to 100 packs per purchase. The price per pack is `purchase.price` in the service document (amount in the currency's smallest unit); each payment challenge states the exact amount. ```http POST https://dashboard-api.audd.io/agent/credits Authorization: Bearer Content-Type: application/json {"packs": 1} ``` The answer is `402 Payment Required` with a `WWW-Authenticate: Payment` challenge (MPP, method `stripe`, intent `charge`). Pay it with an MPP client that supports the `stripe` method and repeat the request with the `Payment-Authorization` header the challenge names, keeping your `Authorization: Bearer` header. The `200` answer carries the new balance and a `Payment-Receipt`. Repeating a request with the same `Payment-Authorization` never charges twice. You can also pay at the recognition endpoint: with a balance of 0 it answers `402` with a challenge for one pack. Pay it and repeat the same recognition request. Credits expire 12 months after your last purchase. Limits: up to 100 packs per purchase; per card or Link account, at most 10 purchases per day and a daily amount cap (`purchase.limits` in the service document), reset at 00:00 UTC. A refused payment charges nothing, and its answer says what to do next (another payment method, a smaller purchase, or when the limit resets). Buy several packs in one purchase ({"packs": N}) rather than many single packs. ### 3. Recognize ```sh curl https://api.audd.io/agent/recognize \ -H "Authorization: Bearer $AUDD_AGENT_KEY" \ -F url='https://audd.tech/example.mp3' \ -F return='apple_music,spotify' ``` Parameters and the response are those of AudD's standard endpoint (https://docs.audd.io/.md): `url`, a multipart `file`, or base64 `audio`, plus the optional `return`. Only the first 12 seconds of the audio are analyzed. `status: "success"` with `result: null` means the audio was processed and no song matched. Size limits: audio file up to 15 MB, as a multipart upload or base64 in the audio parameter (a larger file gets AudD error 400, which is free). The whole request body may be up to 24 MB. Send the key only in the `Authorization` header. A key in a URL or in an `api_token` field is refused; replace such a key, since it may be in logs. Agent keys do not work on AudD's account endpoints (`https://api.audd.io/`, the enterprise endpoint, streams, the MCP server). Charge rule: One credit per request when recognition gave an answer (a match or a no-match) or failed with AudD error 300 (the audio couldn't be fingerprinted) or 19 (internal error). Free: every other error answer, including input errors (no file, a URL that could not be downloaded, unsupported or undecodable audio, a file over 15 MB), unknown errors (100), timeouts and crashes on our side. Answers to requests with a valid key carry `AudD-Credits-Remaining`, `AudD-Credits-Charged` (`0` or `1`) once a credit was reserved, and `AudD-Credits-Low: 1` when you run low. Check `GET https://dashboard-api.audd.io/agent/balance` (with your key) before a long job. ### 4. Manage the registration - `GET https://dashboard-api.audd.io/agent/me`: status, balance, credit expiry. - `POST https://dashboard-api.audd.io/agent/keys`: a new key (shown once). `GET` lists keys; `DELETE https://dashboard-api.audd.io/agent/keys?prefix=agt_xxxxxxxx` revokes one. - `GET https://dashboard-api.audd.io/agent/usage?from=YYYY-MM-DD&to=YYYY-MM-DD`: usage per day. - Lost the key: `POST https://dashboard-api.audd.io/agent/identity` with `{"type": "refresh", "refresh_token": "audd_art_...", "new_api_key": true}`. Each use of a refresh token returns a new one; store it. Reusing an old refresh token more than 60 seconds later revokes every credential of the registration. - `DELETE https://dashboard-api.audd.io/agent/me` revokes the registration and every key. With credits left it answers `409 forfeit_required`; repeat with `?forfeit=true` to confirm. Credits left on a revoked registration stay on record (questions: api@audd.io). - Email verification (optional): `POST https://dashboard-api.audd.io/agent/verify_email` with the methods listed in the service document (email_code). Effect: reachability only: receipts and notices; no limits, scopes or account access change. ### Errors Errors are `application/problem+json` with `audd.code` and `audd.charged` (`true`, `false`, or `null` while unknown). The `type` URI is `https://audd.io/auth.md#error-`; payment problems use `https://paymentauth.org/problems/`. Honor `Retry-After`. | Code | Status | What to do | |---|---|---| | `credential_required` | 401 | Register (step 1), buy (step 2), send `Authorization: Bearer `. | | `invalid_token` | 401 | The key is unknown, revoked or expired. Mint a new key (step 4) or register again. | | `agent_key_wrong_endpoint` | 401 | An agent key was sent to an account endpoint. Recognize at `https://api.audd.io/agent/recognize`. | | `credential_in_url` | 400 | Send the key only in the `Authorization` header, then replace it. | | `no_prepaid_requests`, `credits_expired` | 402 | Balance 0, or the credits expired: pay the challenge and repeat the request, or buy packs (step 2). Nothing was charged. | | `payment_refused` | 402 | Read `audd.reason` and `audd.next_steps`: another payment method, a smaller purchase, or wait for `audd.resets_at`. Nothing was charged. | | `purchase_pending` | 409 | Another purchase is waiting for the bank to confirm it. Poll `audd.purchase_url` or cancel it with `DELETE`; do not pay again. Nothing was charged. | | `idempotency_key_reused` | 409 | This `Idempotency-Key` was used with a different payment challenge. Send a new key (or none) with a new payment; to retry a purchase, repeat its exact request. Nothing was charged. | | `wallet_frozen` | 403 | Purchases and use are stopped for this registration. Contact api@audd.io. | | `too_many_failed_inputs` | 429 | Too many requests this hour that could not be processed (bad URL, unsupported file). Fix the input and wait for `Retry-After`; nothing was charged. | | `rate_limited` | 429 | Slow down; repeat after `Retry-After`. | | `payment_service_unavailable` | 503 | The payment was not sent. Repeat the same request after `Retry-After`. | | `retry_later` | 503 | If `audd.do_not_pay_again` is true, the payment may still complete: repeat with the same `Payment-Authorization`, do not pay again. | | `timeout`, `late_settle` | 504 | Recognition did not finish in time. Not charged; repeat the request. | | `agent_api_paused`, `agent_payments_paused` | 503 | The agent service, or buying, is paused. Nothing was charged; try again later. | | `anonymous_not_enabled` | 400 | Registration is closed right now. Try again later. | | `unsupported_type` | 400 | Only `anonymous` (and `refresh`) registrations are accepted. | | `invalid_refresh_token` | 400 | Register again. | ## With a user's AudD account - **API token (music recognition API)**: Requests to `https://api.audd.io/` and `https://enterprise.audd.io/` authenticate with an `api_token` from the AudD dashboard, sent as a POST field or a query parameter. It is typically provided through the `AUDD_API_TOKEN` environment variable, as in the official SDKs. Get a token: https://dashboard.audd.io/ Documentation: https://docs.audd.io/ - **OAuth 2.1 (account, usage and billing API; MCP server)**: The AudD account API at `https://dashboard-api.audd.io/v1/` and the MCP server at `https://mcp.audd.io` accept OAuth access tokens sent as `Authorization: Bearer `. Authorization code flow with PKCE (S256) and refresh tokens; dynamic client registration and client ID metadata documents are supported. Authorization server metadata: https://dashboard-api.audd.io/.well-known/oauth-authorization-server Protected resource metadata: https://mcp.audd.io/.well-known/oauth-protected-resource - **MCP clients**: Add the server by URL (for example `claude mcp add --transport http audd https://mcp.audd.io/`); the client runs the OAuth flow in the user's browser. Before requesting credentials, check whether the user already has an AudD token configured, for example in `AUDD_API_TOKEN`. Do not ask users to paste API tokens into chat. Read tokens from the environment or a secure secret store at the moment of use, and never print them in logs, commits, pull requests, screenshots, generated docs, or error reports. ## Product Links - Sign up or sign in: https://dashboard.audd.io/ - API documentation: https://docs.audd.io/ ## Legal - Terms: https://audd.io/terms/ - Privacy: https://audd.io/privacy/ ## Contact For AudD API support, email api@audd.io.