X-API-Key header or as an Authorization: Bearer token. API keys are the recommended way to call the API from scripts, CI/CD pipelines and backend services.
Send the key in one header only: either X-API-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY.
Some actions are available only in the dashboard and cannot be performed with an API key, for example managing API keys, projects, billing and your team, and deleting status pages. Projects and organizations cannot be deleted through the API. Requests for these return
403.Create an API key
1
Open the API Keys settings
Sign in at app.uptimeio.com and go to Settings > API Keys.
2
Create the key
Click Create API Key, give it a descriptive name (for example
CI/CD pipeline) and choose a scope (see below).3
Copy and store the key
Copy the key immediately. The full key is shown once; afterwards only a preview such as
uio_1a2b...9f3c is visible.Use an API key
Add the key to theX-API-Key header of every request:
Scopes
Each key has one scope, chosen when it is created. The default isread.
A
read key that sends POST, PUT, PATCH or DELETE receives 403 with code READ_ONLY_API_KEY:
Plans and limits
Plan rules are read on every request, so an upgrade or downgrade takes effect immediately without changing your keys.
Rate limits
Requests made with an API key are limited per organization, across all of its keys, over a rolling 60-second window. A key can also have its own lower limit (rate_limit_per_minute); a request must pass both limits.
Every API-key response carries these headers. When a per-key limit is set, they describe whichever limit is closest to being reached.
When you exceed a limit, the API returns
429 with code RATE_LIMITED and a Retry-After header (seconds):
Retry-After before retrying. See Error Handling.
Organization and project
An API key is issued for one organization and always acts on that organization. The key cannot be redirected to another organization with a header. Monitors, groups and incidents belong to a project. By default requests act on your organization’s default project. To target another project, send its ID in theX-Project-ID header:
- A project that does not exist returns
404with codePROJECT_NOT_FOUND. - A key restricted to one project can only act on that project. Requests for any other project return
403with codeAPI_KEY_PROJECT_MISMATCH. - A project that belongs to a different organization returns
403(for examplePROJECT_ORGANIZATION_MISMATCH, orAPI_KEY_ORGANIZATION_MISMATCHon project-scoped status page routes).
/api/projects/{projectId}/status-pages.
Manage API keys
Create, rotate and delete keys in Settings > API Keys in the dashboard. See API keys. On Pro and Scale you can restrict a key to one project and give it its own request limit there. Rotating a key keeps its permissions, project and request limit.Security best practices
Keep keys out of code
Keep keys out of code
Store keys in environment variables or a secrets manager:
Rotate keys regularly
Rotate keys regularly
Rotate from Settings > API Keys. The old key stops working immediately, so update your applications straight after rotating.
Use one key per service
Use one key per service
Give CI/CD, background jobs and each integration their own key. If one leaks you can revoke it without affecting the others. The key list shows each key’s scope and when it was last used.
Code examples
- cURL
- JavaScript
- Python
Authentication errors
See Error Handling for the full list.
Troubleshooting
401 - the key works in curl but not in code
401 - the key works in curl but not in code
- The environment variable is not set in the runtime (
echo $UPTIMEIO_API_KEY). - The key has a trailing space or newline - trim it.
- The header name must be exactly
X-API-Key.
403 READ_ONLY_API_KEY
403 READ_ONLY_API_KEY
The key has
read scope. Create a read_write key in Settings > API Keys.403 PLAN_UPGRADE_REQUIRED
403 PLAN_UPGRADE_REQUIRED
Restricting a key to one project, or giving it its own request limit, needs Pro or Scale. Any plan can create a
read_write key.429 RATE_LIMITED
429 RATE_LIMITED
Your organization (or the key’s own cap) used its requests for the minute. Wait
Retry-After seconds, and spread requests out or share results between jobs.403 on a project or status page route
403 on a project or status page route
The key was issued for a different organization than the project you are addressing. Use a key created in the owning organization.