Authentication
Every API request must include a valid API key in the X-API-KEY header.
curl -X POST \
"https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/api" \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-api-key" \
-d '{ ... }'
API keys
Each key is scoped to a single project. One project, one key.
Environment separation. Staging and production use different keys. A staging key does not authenticate against the production URL. Your project hash is the same across environments, but the keys are not interchangeable.
Storage. Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). Never commit keys to version control, embed them in client-side JavaScript, or log them in application output.
Store API keys in a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) for production deployments. Environment variables are the minimum acceptable approach.
# Environment variable
export ZENOO_API_KEY="your-api-key"
# Use in your application
curl -H "X-API-KEY: $ZENOO_API_KEY" ...
Key rotation
Contact Zenoo support to rotate your API key. The process:
Request a new key
Contact Zenoo support to request a new API key for your project.
Receive the new key
Zenoo generates the new key and revokes the old one immediately.
Deploy the new key
Deploy the new key to all applications, environment variables, and CI/CD secrets immediately after receiving it.
There is no grace period where both keys are active. Plan your deployment before requesting rotation. Update all configuration, environment variables, and CI/CD secrets, then deploy immediately after receiving the new key.
Error responses
| Status | Error Code | Meaning |
|---|
401 | UNAUTHORIZED | The X-API-KEY header is missing or the key is invalid |
403 | FORBIDDEN | The key is valid but does not have access to this project |
401 Unauthorized
{
"error": "UNAUTHORIZED",
"message": "Missing or invalid API key",
"request_id": "req-a1b2c3d4"
}
X-API-KEY header is present and contains the correct key for your environment. If the key was recently rotated, retrieve the new key from your secrets manager.
Do not retry 401 errors. The same key will fail every time.
403 Forbidden
{
"error": "FORBIDDEN",
"message": "API key does not have access to this project",
"request_id": "req-e5f6g7h8"
}
Security rules
- Never expose API keys in client-side code (browser JavaScript, mobile apps).
- Never commit keys to Git repositories, even private ones.
- Never log API keys in application output or error messages.
- Store keys in environment variables or a dedicated secrets manager.
- Use HTTPS for all API requests. HTTP is not supported.
- Rotate keys immediately if a compromise is suspected.
