# auth.md

How agents authenticate with Brandfetch. The REST APIs live on `api.brandfetch.io`, the Logo CDN on `cdn.brandfetch.io`, and the MCP server on `mcp.brandfetch.io`. Credentials are created and managed at [developers.brandfetch.com](https://developers.brandfetch.com).

This file follows the [auth.md convention](https://workos.com/auth-md). Programmatic agent registration is not supported yet: credentials come from a one-time browser sign-up completed by your user (see [Get credentials](#get-credentials-user-claimed)). Once you hold a credential, every request is a plain HTTP header or query parameter — no token exchange, no refresh flow.

## Discover

Every brandfetch.com response carries an RFC 8288 `Link` header pointing at the machine-readable surfaces: the [API catalog](https://brandfetch.com/.well-known/api-catalog) (RFC 9727 — every public API with its OpenAPI description, documentation, and status), the [OpenAPI description](https://docs.brandfetch.com/openapi.json), and [/llms.txt](https://brandfetch.com/llms.txt). This file covers the one thing those don't: how to get and use credentials.

## Credentials

Three credential types, all issued on one dashboard page: [developers.brandfetch.com/dashboard/keys](https://developers.brandfetch.com/dashboard/keys).

| Credential | APIs | How to send it | Secrecy |
| --- | --- | --- | --- |
| API key | Brand API, Brand Context API, Transaction API (enterprise) | `Authorization: Bearer {API_KEY}` header | Secret — keep out of URLs, logs, and client-side code |
| Client ID | Logo API, Brand Search API | `?c={CLIENT_ID}` query parameter | Publishable — safe to embed in URLs and HTML |
| MCP token | MCP server, only when the client can't do OAuth | `Authorization: Bearer {MCP_TOKEN}` header | Secret |

## Get credentials (user-claimed)

There is no unattended sign-up: hand your user a URL, then wait for them to paste the credential back.

1. Send the user to [developers.brandfetch.com/register](https://developers.brandfetch.com/register) to create a developer account, or [developers.brandfetch.com](https://developers.brandfetch.com) to sign in. The Free plan needs no credit card: 100 brand fetches (one-time), 1M Logo API requests/month, 500K Brand Search API requests/month.
2. The user copies the API key, client ID, or MCP token from [developers.brandfetch.com/dashboard/keys](https://developers.brandfetch.com/dashboard/keys).
3. Store what they hand back — suggested environment variables: `BRANDFETCH_API_KEY`, `BRANDFETCH_CLIENT_ID`, `BRANDFETCH_MCP_TOKEN`.

Don't send the user to `brandfetch.com/register` — that is the Brandspace sign-up for brand owners managing their own profile. It issues no API credentials.

## Use the credentials

**Brand API** — the full brand profile: logos, colors, fonts, firmographics. `{type}` is one of `domain`, `ticker`, `isin`, `crypto`. 1 credit per call:

```http
GET https://api.brandfetch.io/v2/brands/domain/shopify.com
Authorization: Bearer {API_KEY}
```

**Brand Context API** — grounded brand context for LLMs: mission, voice, positioning, audience, products, competitors. Any live domain resolves. 1 credit per call:

```http
GET https://api.brandfetch.io/v2/context/shopify.com
Authorization: Bearer {API_KEY}
```

**Logo API** — logos straight from the CDN, free up to 1M requests/month. The client ID rides in the URL:

```
https://cdn.brandfetch.io/shopify.com?c={CLIENT_ID}
```

**Brand Search API** — company name → canonical domain, free up to 500K requests/month:

```http
GET https://api.brandfetch.io/v2/search/shopify?c={CLIENT_ID}
```

**Viewer API** — verify a credential. Returns the identity behind the key plus credit usage and quota. Free — never consumes credits. Takes the Bearer API key, not the client ID:

```http
GET https://api.brandfetch.io/v2/viewer
Authorization: Bearer {API_KEY}
```

A `200` confirms the key is valid; `401`/`403` means missing, invalid, or revoked. Call it right after the user hands you a key, and in health checks. Docs: [Viewer API reference](https://docs.brandfetch.com/reference/viewer-api).

Full request and response schemas: [docs.brandfetch.com](https://docs.brandfetch.com) and the [OpenAPI description](https://docs.brandfetch.com/openapi.json).

## MCP (OAuth)

The MCP server carries the one programmatic OAuth flow.

- Endpoint: `https://mcp.brandfetch.io/mcp` (HTTP transport, no credentials in the URL)
- Authorization server metadata: [developers.brandfetch.com/.well-known/oauth-authorization-server](https://developers.brandfetch.com/.well-known/oauth-authorization-server)
- Grant: `authorization_code` with PKCE (`S256`), public client (`token_endpoint_auth_methods_supported: ["none"]`)
- Dynamic client registration: supported (`registration_endpoint` in the metadata)
- Scope: `read`

The authorization step opens a browser where your user signs in with Brandfetch. If the MCP client can't do OAuth, send an MCP token from the dashboard as `Authorization: Bearer {MCP_TOKEN}` instead.

These OAuth tokens work only against the MCP server. They are not valid on `api.brandfetch.io` — the REST APIs take the API key and client ID above. `api.brandfetch.io` publishes no `/.well-known/oauth-protected-resource` yet.

## Limits

Brand API, Brand Context API, the enterprise-only [Transaction API](https://docs.brandfetch.com/transaction-api/overview), and webhook subscriptions share one monthly credit pool — 1 credit per call, and 1 credit per subscribed brand per month for webhooks. Logo API and Brand Search API run on separate, free quotas. On the Growth plan, brand fetches over the monthly limit bill at $0.10 each up to a configurable cap. Logo API and Brand Search API are soft-capped — going over triggers a notification, not a hard stop. Plans: [brandfetch.com/developers/pricing](https://brandfetch.com/developers/pricing).

## Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 | Missing or invalid credential | Verify the key with a free [Viewer API](https://docs.brandfetch.com/reference/viewer-api) call, and confirm the credential type matches the API — Bearer API key vs `?c=` client ID (see [Credentials](#credentials)) |
| 404 | No brand for that identifier | Resolve the name to a domain with the Brand Search API first |
| 429 | Rate or quota limit hit | Back off and retry; check usage in the dashboard |

## Revocation

Your user rotates or revokes credentials at [developers.brandfetch.com/dashboard/keys](https://developers.brandfetch.com/dashboard/keys). Treat a 401 on a previously working key as revocation, not an outage — confirm with a free Viewer API call, and check uptime at [status.brandfetch.io](https://status.brandfetch.io).

## More for agents

- [/llms.txt](https://brandfetch.com/llms.txt) — full machine-readable overview: APIs, pricing, FAQ, agent instructions.
- [/agent-onboarding/SKILL.md](https://brandfetch.com/agent-onboarding/SKILL.md) — task-oriented onboarding: pick an API, get credentials, call it.
- [/.well-known/api-catalog](https://brandfetch.com/.well-known/api-catalog) — RFC 9727 catalog: every public API with its OpenAPI description, documentation, and status.
- [docs.brandfetch.com](https://docs.brandfetch.com) — reference documentation.