# auth.md

Instructions for AI agents and other automated clients that need to call the
Bluejay API or the Bluejay MCP server.

## Bluejay is not an OAuth authorization server

Bluejay does not run an OAuth 2.0 or OpenID Connect authorization server. There
is no `/authorize` endpoint, no `/token` endpoint, no dynamic client
registration, and no client_id or client_secret is ever issued. Do not attempt
an OAuth flow against getbluejay.ai or api.getbluejay.ai. The only credential
Bluejay accepts from third-party clients is an API key.

## Credential

An API key is a bearer secret scoped to a single Bluejay organization. Treat any
key as full access to that organization's data.

Send it on every request in the `X-API-Key` header:

```http
X-API-Key: <your_api_key>
```

`Authorization: Bearer <your_api_key>` is also accepted. Bluejay additionally
accepts session tokens issued by its own dashboard sign-in on the
`Authorization` header, but those are not available to third-party clients and
agents should not try to obtain one.

## Getting the first key

There is no anonymous self-registration. A human with a Bluejay account creates
the first key:

1. Sign in at https://app.getbluejay.ai
2. Go to Settings, then API Keys (https://app.getbluejay.ai/settings/api-keys)
3. Generate a key and copy it immediately. It is shown once.

Accounts are available at https://getbluejay.ai/signup.

## Provisioning and revoking further keys

Once a client holds a valid credential it can manage keys over the API.

- Create: `POST https://api.getbluejay.ai/v1/api-keys`
- Revoke: `DELETE https://api.getbluejay.ai/v1/api-keys/{key_id}`

Both require an existing credential for the same organization. Revocation
additionally requires a full-scope key. Full request and response schemas are in
the OpenAPI document.

## Endpoints

| Purpose | URL |
|---|---|
| REST base | https://api.getbluejay.ai/v1 |
| OpenAPI description | https://api.getbluejay.ai/openapi.json |
| API reference | https://docs.getbluejay.ai/api-reference/introduction |
| MCP server (Streamable HTTP) | https://api.getbluejay.ai/mcp |
| MCP documentation | https://docs.getbluejay.ai/mcp/overview |
| Health | https://api.getbluejay.ai/health |

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing or invalid credential |
| 403 | Credential is valid but has no organization, or lacks the scope required |