# Authentication (https://docs.walido.it/docs/authentication)

Public API keys are sent as `Authorization: Bearer <key>`. Newly issued keys are
~43-character base64url strings with no prefix; legacy `smao_`-prefixed keys
remain valid.

## MCP Connector - OAuth or organization API key [#mcp-connector---oauth-or-organization-api-key]

For an interactive AI client, add `https://api.walido.it/mcp` as a remote MCP
connector and use OAuth. The client discovers Walido's authorization server,
opens the browser login and consent flow, and binds the connection to the
organization you select. Disconnect and reconnect to switch organizations.

Clients that support custom HTTP headers can instead send a Public API
organization key as `Authorization: Bearer <key>`. Both methods apply the
current organization role and plan entitlements on every request. See the
[MCP setup and access rules](/docs/mcp) for client examples, scopes, and
revocation.

## Public API - organization API keys [#public-api---organization-api-keys]

Create keys yourself in the dashboard under **Settings → API Keys → New key**.
Each key gets a **Role** that scopes what it can do - pick the narrowest role
that covers your use case. Keys belong to one organization; every request is
scoped to that organization's data.

```bash
curl https://api.walido.it/api/v1/ping \
  -H "Authorization: Bearer <your_api_key>"
```

A missing or invalid key returns `401`:

```json
{ "error": { "code": "unauthorized", "message": "Missing API key" } }
```

A valid key whose role lacks permission for the endpoint returns `403` with
`error.code: "forbidden"`. If the key's organization is blocked, every request
returns `403` with `error.code: "organization_blocked"`. See [Errors](/docs/errors) for the full envelope.

<Callout type="warn">
The raw key is shown once, at creation. Store it in a secret manager - it cannot be retrieved later.
</Callout>

Key handling:

- **One key per integration.** Separate keys let you revoke one consumer without breaking the others.
- **Rotate by overlap.** Create a new key, deploy it, then delete the old one. Both work in parallel in between, so rotation needs no downtime.
- **Revoke immediately on leak.** Deleting a key invalidates it at once.

Rate-limit headers and retry rules are in [Errors & Rate Limits](/docs/errors).
