API keys

An API key lets a script, a tool or an AI agent call the OctoPing API as a person in your workspace. This page covers how to create a key, the three access levels, how to send a key, what a key can reach, the limits, every error code, and what happens when you rotate or revoke a key, when people change roles and when a workspace pauses. The operations a key can call are in the API reference.

Create a key

Members, Admins and Owners create keys in the web app. Viewers can't. Every plan can create keys, the trial included, and the number of keys depends on the plan (see Limits). A key is created by a person and belongs to the workspace. Creating one needs a verified email address.

• Admins and Owners open Settings and choose Manage API keys in the API keys card.
• Members open the Account page and choose Manage API keys in the API Keys card.

1. 1. Choose Create key

   The button is at the top of the API keys page.

2. 2. Enter a Name

   Use something you will recognise later, such as the tool that uses the key. A name can be up to 100 characters.

3. 3. Pick the Access

   Choose Read only, Read and write or Admin. A Member sees the first two. The next section says what each one allows.

4. 4. Set Expires on, if you want an expiry

   Leave the date empty and the key never expires. With a date, the key works until the end of that day in your time zone.

5. 5. Copy the key

   OctoPing shows the key once, with a Copy button. It can't show the key again. If you lose it, rotate the key to get a new one.

A key starts with op_live_. The key list shows its first characters so you can tell your keys apart.

A workspace that already has every key its plan includes can't create another. The app shows the notice "Your plan's API keys are all in use". Revoking a key, or letting one expire, frees its place.

Access levels

A key never does more than the person who created it can do at that moment. The access you choose is a ceiling, and the creator's current role can lower it.

Use a key

Send the key in the X-API-Key header on every request. The base address is:

https://octoping.com/api

export OCTOPING_API_KEY="op_live_..."
curl -fsS -H "X-API-Key: $OCTOPING_API_KEY" https://octoping.com/api/webpages

• Send the key in the header only. A key in a URL or in an Authorization: Bearer header is not read. When a request carries X-API-Key, OctoPing ignores its cookies and its Authorization header.
• The key identifies its workspace, so send no X-Workspace-ID header and no workspace_id parameter. If you send one, it has to be the key's workspace, or the request is refused with workspace_mismatch.
• Send a request body as JSON, with Content-Type: application/json.
• Call the API over https. The base address above already does. A request sent to http:// with a key is refused with https_required, and the key it carried crossed the network without encryption, so treat the key as exposed and rotate it.
• Keep the key on a server, in an environment variable or a secret store. Don't put it in code that runs in a browser, in a repository or in a URL.

What a key can reach

A key calls the operations in the API reference and the group monthly summary. Together they cover:

• Sites, their settings and current status, check history, stats, outages, and the certificate, DNS, hosting, domain and robots.txt checks.
• Heartbeats and their pings.
• Groups and each group's monthly summary.
• Maintenance windows.
• Status pages (read only) and their incidents.

A read key is not given the credentials a response carries. A heartbeat's ping_url and secret_key and a site's custom_headers come back null, and a site's feature_config comes back without its webhook_secret entry. A read key also gets a site's address without any user name and password written into it, so https://user:pass@example.com/ comes back as https://example.com/, wherever the address appears. A read and write key or an admin key gets them as stored, so a script that needs a ping URL uses one of those. The query string of an address is returned as stored, so keep secrets out of it.

Other parts of the product stay in the web app and cannot be reached with a key:

• Alert channels and the notification log.
• Uploads, such as a status page logo.
• Custom domains, subscribers and contacts.
• Bulk actions on many sites at once.
• Members, invitations, billing and plans.
• API keys. A key can't create, rotate or revoke keys.
• Creating or editing a status page. A key reads pages and manages their incidents.

Limits

Limits count the requests of the whole workspace, and every key in it shares them. They are not per key. The plan sets how many keys the workspace can hold and how many requests it can make.

• The day runs from midnight to midnight UTC. The minute window ends at the next full minute.
• A request refused for the minute limit, the day limit or too many requests within one second doesn't count against the limits. A 429 with the code summary_in_progress does count, because the request had already been admitted when it was refused.
• Sending a very large number of requests within the same second is refused with a 429 too, whatever is left of your limits. Spread bursts out and wait for Retry-After.

Admins and Owners can see where the workspace stands on the Billing page, under API keys, API requests today and API requests per minute. The key list shows each key's requests today and in the last 30 days.

Rate limit headers

A response to a request made with a valid key normally carries these headers, an error response included. The exception is the 429 for too many requests within the same second, which carries only Retry-After. Don't depend on the headers being there. Read them when they are, and when they aren't, rely on the 429 and its Retry-After.

Print the headers of one response to see where the workspace stands.

curl -sS -D - -o /dev/null -H "X-API-Key: $OCTOPING_API_KEY" https://octoping.com/api/webpages

A request over the minute limit is refused like this. The numbers are an example.

HTTP/2 429
retry-after: 23
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
x-ratelimit-reset: 1790000040
x-ratelimit-daily-limit: 10000
x-ratelimit-daily-remaining: 9412
x-ratelimit-daily-reset: 1790035200

{"code": "rate_limited", "detail": "Too many requests this minute. Wait for the next minute to send more."}

Errors

A request that is refused because of the key, the workspace's state, its plan or the way it was sent answers with a JSON body that has a code and a detail. Branch on the code. The codes are stable, and the wording of detail can change.

{"code": "insufficient_scope", "detail": "..."}

A write can also be refused with a 403 and a code for a plan or an account limit. The codes are email_unverified, trial_expired, payment_required, subscription_ended, monitor_limit, heartbeat_limit, interval_limit and fast_check_limit. The app shows the same ones, and the table under Refusals when adding a site on Plans and billing says what fixes each.

Other answers use the usual HTTP statuses. A site, heartbeat, group, window or incident that isn't in your workspace answers 404, the same as one that doesn't exist. A request body that can't be accepted answers 422, and a name that is already taken answers 409. These carry a detail and some also carry a code, so read the status first.

Rotate a key

Rotating replaces a key with a new one and stops the old one at once. Use it when a key may have been seen by someone who shouldn't have it, or when the person who knew it leaves.

• Choose Rotate next to the key and confirm. The new key is shown once, like any new key.
• The old key stops working before the new one appears. There is no overlap, so anything still using the old key fails until you give it the new one. Rotate when you can update the tool right away.
• The new key keeps the name, the access and the expiry. Its request counts start again, and it needs no free place in the plan's allowance.
• An Admin or Owner can rotate someone else's key. The new key is listed under the name of the person who rotated it and acts as that person.
• An expired key can't be rotated, because the new key would already be expired. Revoke it and create a new one.

Revoke a key

Choose Revoke next to the key and confirm. The key stops working at once, can't be restored, disappears from the list and frees its place in the plan's allowance. Create a new key if the tool still needs access.

Who sees and manages keys

• Admins and Owners see every key in the workspace and can rotate or revoke any of them.
• Members see the keys they created and manage only those. The count at the top shows the whole workspace's use of the allowance.
• The list shows each key's name, its first characters, who created it and when, its access, when it was last used, when it expires and its requests today and in the last 30 days. Last used can be up to 5 minutes behind.

When people change roles or leave

A key acts as the person who created it, so it follows that person's role in the workspace. The key list shows which keys have changed.

Create a key as the person whose access you want a tool to have. If that person's role changes, review the keys they made.

Paused workspaces

A workspace pauses when its trial ends with no plan, when a failed payment's grace window runs out or when a subscription ends. Its history is kept for 30 days, and keys can read it for that long.

• For 30 days after the pause, keys keep working. Reads return the history that is kept.
• Adding a site or a heartbeat, and check now, are refused with the same code the web app shows, which is trial_expired, payment_required or subscription_ended.
• After that, every request made with a key is refused with api_paused. Restoring the plan or fixing the payment switches keys back on.
• You can still create keys in a paused workspace, so you can export history. A key made after the history window has passed answers api_paused until the workspace is restored.

The Plans and billing page describes what pausing stops and what it keeps.

Good practice

• Create one key for each tool and name it after the tool. Revoking one then stops one tool, and Last used shows which tools are active.
• Choose Read only unless the tool changes something, and Admin only for a tool that deletes.
• Set an expiry on a key made for a project with an end date.
• Store keys as secrets, and rotate a key when someone who knew it leaves.
• Prefer webhooks to polling. A script that polls every 30 seconds makes 2,880 requests a day. A webhook notification tells your server when something changes and uses none of the workspace's requests.
• Read X-RateLimit-Remaining when it is there, and slow down before it reaches zero. When a 429 arrives, wait for Retry-After.
• Don't poll the group monthly summary. OctoPing reuses an answer for 5 minutes, or 60 minutes once the month is over.