Skip to main content
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: 
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: 
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. 
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: 
{
  "id": "proj_...",
  "name": "My Project",
  "apiKey": "rly_live_xxxxxxxxxxxxxxxxxxxx"
}
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.

​
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: 
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. 
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.
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.

​
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.