API keys are the credentials that authenticate requests to the Underlayer API. Each key belongs to a single workspace and grants full access to that workspace.

Creating a key

1. Open your workspace and go to Settings → API Keys
2. Click New API key
3. Enter a descriptive name (e.g. backend-prod, github-actions)
4. Copy the key immediately. It will not be shown again

Using a key

Pass the key in the X-Api-Key header:

curl https://api.underlayer.dev/api/v1/scheduler/tasks \
  -H "X-Api-Key: ul_live_xxxxxxxxxxxxxxxxxxxx"

Key naming conventions

A descriptive name helps you audit which service uses which key. Recommended patterns:

• production-api: your main backend in production
• staging-api: staging environment
• ci-deploy: CI/CD pipeline
• local-dev-alvaro: personal local development

Revoking a key

Go to Settings → API Keys, find the key by name (and last 4 characters), and click Revoke. Revocation is instant: all requests using that key immediately receive a 401 Unauthorized response.

Rotation best practices

• Rotate keys when an employee with access leaves
• Rotate immediately if a key is accidentally exposed (e.g. committed to a repo)
• Create the new key before revoking the old one to avoid downtime

All API key operations are visible in Settings → API Keys and require admin role in the workspace.