Skip to Content
WalidoDocs

Authentication

OAuth and organization API keys for MCP, and Public API keys.

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

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 for client examples, scopes, and revocation.

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.

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

A missing or invalid key returns 401:

{ "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 for the full envelope.

The raw key is shown once, at creation. Store it in a secret manager - it cannot be retrieved later.

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.

On this page