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

# Authentication

> Authenticate every request with your workspace API key.

Every request needs your workspace API key as a bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.blujay.io/v1/me \
  -H "Authorization: Bearer blu_your_api_key"
```

## API keys

Workspace owners and admins find the key in [Blujay](https://app.blujay.io) under **API** in the sidebar, in the **API Token** card. Use the eye button to reveal it.

A workspace has one API key today. It has full access to its workspace: it can send messages from your numbers and read every chat. Treat it like a password.

* Keep it on your server, in an environment variable or a secret manager.
* Never put it in a web page, a mobile app, a URL or source control.
* Don't log it, and don't send it to support. Send the `trace_id` instead.

> [!WARNING]
>
> **Call the API from your server.** Browsers block requests to the API from other websites, so code running in a web page can't call it directly, and shouldn't: it would expose your key. Send requests from your backend and pass the results to your page.

To rotate the key, or if it leaks, email [support@blujay.io](mailto:support@blujay.io). There is no self-service rotation and no second key yet. A revoked key returns [`API_KEY_REVOKED`](/errors/api-key-revoked). The key from the **API** tab doesn't expire; a key that support issued with an expiry date returns [`API_KEY_EXPIRED`](/errors/api-key-expired) after that date.

## Test and live

There is one mode: live. Keys don't have a test or sandbox variant, and every call acts on your real workspace. Messages you send are delivered, and contacts you create are saved.

To test safely:

* Send to your own phone number first.
* Use a clear prefix in your `Idempotency-Key` values (for example `test-…`) so you can find test sends quickly.
* Point a webhook subscription at a test endpoint. If you have more than one number, filter the subscription to the number you test with. See [Select phone numbers](/webhooks/overview.md#select-phone-numbers).

## Check a credential

`GET /v1/me` tells you which workspace and key a request uses:

```json theme={null}
{
  "status": "success",
  "data": {
    "workspace_id": "workspace_abc123",
    "workspace_label": "Acme Support",
    "credential": { "type": "api_key", "id": "3f6c2a7e-1b9d-4e5a-9c1f-2d7b8a6e4c10", "status": "active" },
    "api_key": { "id": "3f6c2a7e-1b9d-4e5a-9c1f-2d7b8a6e4c10", "status": "active" }
  },
  "trace_id": "trc_9d1f0a7c2b4e",
  "timestamp": "2026-10-14T17:00:00.000Z"
}
```

`credential` and `api_key` describe the same key. Prefer `credential`; `api_key` stays for older clients. Credential IDs are plain UUIDs, not prefixed IDs.

## Authentication errors

| Code | Status | Meaning |
| - | - | - |
| [`UNAUTHORIZED`](/errors/unauthorized) | 401 | No API key, or not a valid one. |
| [`API_KEY_REVOKED`](/errors/api-key-revoked) | 401 | The key was revoked. |
| [`API_KEY_EXPIRED`](/errors/api-key-expired) | 401 | A key that support issued with an expiry date passed it. |

Repeated failed authentication from one IP address is limited to 60 attempts a minute. See [Rate limits](/rate-limits.md).

## Next steps

> **[Quickstart](/quickstart.md)**
>
> Send your first message in about five minutes.

> **[Making requests](/making-requests.md)**
>
> Response format, IDs, pagination and tracing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.