Skip to main content
UptimeIO API requests are authenticated with an API key sent in the 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.
Only organization owners and admins can create, rotate or delete API keys. See API keys for managing keys in the dashboard. If you lose a key, rotate it or create a new one and delete the old one.

Use an API key

Add the key to the X-API-Key header of every request:
Or send it as a Bearer token. Both forms are equivalent:

Scopes

Each key has one scope, chosen when it is created. The default is read. A read key that sends POST, PUT, PATCH or DELETE receives 403 with code READ_ONLY_API_KEY:
Use read keys for dashboards and reporting, and read_write keys only where you need to change things.

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):
Wait for 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 the X-Project-ID header:
  • A project that does not exist returns 404 with code PROJECT_NOT_FOUND.
  • A key restricted to one project can only act on that project. Requests for any other project return 403 with code API_KEY_PROJECT_MISMATCH.
  • A project that belongs to a different organization returns 403 (for example PROJECT_ORGANIZATION_MISMATCH, or API_KEY_ORGANIZATION_MISMATCH on project-scoped status page routes).
Status page endpoints take the project in the URL instead: /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

Store keys in environment variables or a secrets manager:
Rotate from Settings > API Keys. The old key stops working immediately, so update your applications straight after rotating.
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

Authentication errors

See Error Handling for the full list.

Troubleshooting

  • 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.
The key has read scope. Create a read_write key in Settings > API Keys.
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.
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.
The key was issued for a different organization than the project you are addressing. Use a key created in the owning organization.