> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dmly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with a workspace API key, sent as the x-api-key header.

Every request carries a **workspace API key**. The key does two jobs: it authenticates the
caller, and it selects the workspace — which is why no endpoint takes a workspace id.

## Sending the key

Send it as the `x-api-key` header:

```bash theme={"dark"}
curl https://dash.dmly.io/api/v1/contacts \
  -H "x-api-key: dmly_xxxxxxxxxxxx"
```

A bearer token is also accepted, if that suits your HTTP client better:

```bash theme={"dark"}
curl https://dash.dmly.io/api/v1/contacts \
  -H "Authorization: Bearer dmly_xxxxxxxxxxxx"
```

Both are equivalent. If both are present, `x-api-key` wins.

## Creating a key

<Steps>
  <Step title="Open Integrations">
    In DMLY, go to **Salesbot → Integrations** and select the **REST API** tile.
  </Step>

  <Step title="Create a key">
    Give it a name describing what will use it — "Zapier", "Website form", "n8n". The name
    is how you will recognise it later when revoking.
  </Step>

  <Step title="Copy it now">
    The key is shown **once**. DMLY stores only a SHA-256 hash of it, so it cannot be
    retrieved or emailed to you afterwards.
  </Step>
</Steps>

<Warning>
  A key grants full access to everything in its workspace. Treat it like a password: keep
  it server-side, never commit it, and never put it in browser or mobile app code where a
  user can read it.
</Warning>

## Rotating and revoking

Create the replacement key first, deploy it, then revoke the old one — revocation takes
effect immediately and any caller still using the old key starts getting `401`.

DMLY stamps `last_used_at` on every authenticated request, so you can tell whether a key is
still in use before retiring it.

## When authentication fails

| Status | Body                                                                    | Meaning                         |
| ------ | ----------------------------------------------------------------------- | ------------------------------- |
| `401`  | `API key missing. Send it as the "x-api-key" header or a Bearer token.` | No key on the request           |
| `401`  | `Invalid API key.`                                                      | Unknown or revoked key          |
| `401`  | `The workspace for this API key no longer exists.`                      | The workspace was deleted       |
| `403`  | `API access is disabled for this installation.`                         | The API feature is switched off |

See [Errors](/api-reference/errors) for the full list.