# auth.md

## Who this is for

AI agents and scripts that want to act on **wacrm**, the open-source
WhatsApp CRM (https://wacrm.tech). Two things are worth separating:

- **wacrm.tech** (this site) is documentation. It has no user accounts, no
  login and no protected endpoints. Everything here is public; nothing needs
  a credential. There is therefore no OAuth authorization server or
  protected-resource metadata to discover.
- **A wacrm instance** is a self-hosted deployment run by a team on their own
  domain. Its REST API (`/api/v1`) and its MCP server are protected by
  **API keys** issued by that team. wacrm.tech cannot issue them.

## Registration

There is no automated registration endpoint. A human admin or owner of the
instance creates a key in the wacrm dashboard under **Settings → API keys →
New API key**, names it after the integration, grants only the scopes it
needs, and copies it. The key is shown exactly once; the instance stores only
a SHA-256 hash.

If you are an agent acting for such a user, ask them to create the key and
place it in an environment variable rather than pasting it into chat.

## Identity and credential types

- Identity: the key is **account-scoped** — it acts as one account on one
  instance. There is no cross-account access and no user impersonation.
- Credential: an opaque string prefixed `wacrm_live_`, sent as a bearer
  token:

```http
Authorization: Bearer wacrm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

- Scopes: `messages:send`, `messages:read`, `contacts:read`,
  `contacts:write`, `conversations:read`, `broadcasts:send`,
  `webhooks:manage`. A key with no scopes can still call `GET /api/v1/me`
  to verify itself.

## Using the credential

- REST: `https://<instance>/api/v1`. OpenAPI description:
  https://wacrm.tech/.well-known/openapi/wacrm-v1.json. Documentation:
  https://wacrm.tech/docs/public-api.
- MCP: the `wacrm-mcp` npm package (stdio) reads `WACRM_BASE_URL` and
  `WACRM_API_KEY` from its environment and is read-only unless
  `WACRM_ENABLE_WRITES` is set. Manifest:
  https://raw.githubusercontent.com/ArnasDon/wacrm/main/mcp-server/server.json
- Rate limit: 120 requests per minute per key; `429` responses carry
  `Retry-After` and `X-RateLimit-*` headers.

## Errors

`401 unauthorized` — missing or invalid key. `403 forbidden` — the key lacks
the scope. Both return `{ "error": { "code", "message" } }`.

## Revocation

The instance admin revokes a key under **Settings → API keys → Revoke**; it
stops working on its next request. There is no self-service revocation URL
for the key holder.

## Contact

Source and issue tracker: https://github.com/ArnasDon/wacrm. Maintainer: https://wacrm.tech/about.