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

# API Key Authentication for RelayOS Requests

> RelayOS uses Bearer token authentication. Learn how to get your first API key, pass it in requests, create additional keys, and revoke compromised ones.

Every request to the RelayOS API must include a valid API key in the `Authorization` header. RelayOS uses the standard HTTP Bearer token scheme — no session cookies, no OAuth flows, no signature calculations. You include your key in the header, and RelayOS either processes the request or returns a `401 Unauthorized` error.

## Bearer token format

Include your API key as a Bearer token on every authenticated request:

```bash theme={null}
Authorization: Bearer rly_live_xxxxxxxxxxxxxxxxxxxx
```

All RelayOS API keys begin with the prefix `rly_live_`. A request without a valid `Authorization` header, or with a revoked or malformed key, receives a `401` response.

Here is a complete example showing the header in context:

```bash theme={null}
curl -X POST https://api.relayos.com.br/v1/messages \
  -H "Authorization: Bearer rly_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999998888",
    "template": "hello_world",
    "language": "en_US"
  }'
```

## How to get your first API key

Your first API key is issued automatically when you create a project via `POST /v1/projects`. You do not need an existing key to make this call — project creation is the unauthenticated entry point into the API.

```bash theme={null}
curl -X POST https://api.relayos.com.br/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "ownerEmail": "you@yourcompany.com"
  }'
```

The response includes an `apiKey` field:

```json theme={null}
{
  "id": "proj_...",
  "name": "My Project",
  "apiKey": "rly_live_xxxxxxxxxxxxxxxxxxxx"
}
```

<Warning>
  RelayOS displays the API key only once in the project creation response. It is not retrievable afterwards. Copy it to a secrets manager or environment variable immediately. If you lose it, you must create a new key and revoke the old one.
</Warning>

## Create additional API keys

You can create multiple API keys under the same project — for example, one per environment (staging, production) or one per service in a microservices architecture. Use `POST /v1/api-keys` with an existing key to authenticate the request:

```bash theme={null}
curl -X POST https://api.relayos.com.br/v1/api-keys \
  -H "Authorization: Bearer rly_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'
```

The response returns the new key in the same single-display format. Store it before the response body leaves your terminal.

## Revoke a key

When you rotate keys, decommission a service, or suspect a key has been exposed, revoke it immediately with `DELETE /v1/api-keys/{id}`. Revocation is instant — any in-flight or subsequent request using the revoked key receives `401`.

```bash theme={null}
curl -X DELETE https://api.relayos.com.br/v1/api-keys/key_... \
  -H "Authorization: Bearer rly_live_xxxxxxxxxxxxxxxxxxxx"
```

You need the key's `id`, not the key value itself, to revoke it. Retrieve the ID from the key creation response or from `GET /v1/api-keys` if you need to list all active keys for your project.

<Warning>
  Never commit an API key to source control or include it in client-side code. If a key appears in a public repository, revoke it immediately and issue a new one. Use environment variables or a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Doppler) to inject keys at runtime.
</Warning>

## Key management best practices

* **One key per environment.** Use separate keys for local development, staging, and production. This limits the blast radius of a compromised key and makes rotation straightforward.
* **Rotate keys periodically.** Create a replacement key, update your services to use it, verify traffic is healthy, then revoke the old key.
* **Revoke unused keys immediately.** If a service is decommissioned or a contractor's access ends, revoke their key on the same day.
* **Monitor for unexpected usage.** If you see requests you did not initiate, treat it as a potential exposure and rotate all keys for that project.