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.
Include your API key as a Bearer token on every authenticated request:
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:
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.
The response includes an apiKey field:
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:
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.
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.