API automation
Configure a workspace with an API key
Create a scoped automation credential and configure users, schedules, policies, services, and integration keys through the tenant API.
Use the tenant management API to configure your workspace without borrowing a person’s console session. A named API key belongs to one workspace and carries only the scopes you grant. Workspace roles and automation scopes are separate: a key cannot manage billing or issue member credentials, even when an owner created it.
Before you begin
Use a dedicated test workspace, an owner or administrator console session to create the key, one existing enabled demo responder for retained-history cleanup, and a secure place to capture one-time credentials. Creating resources can affect plan seat usage; use your test workspace for this walkthrough.
Create and maintain a key
Sign in to the tenant console as an owner or administrator and open API keys. Give the key a name that identifies its caller, choose its scopes, and set an expiry of 1–365 days. For a recurring integration, create a Service account and assign the key to it so its identity survives credential replacement.
Copy the secret when it is shown: subsequent lists show its masked display, expiry, status and last-used time, not the secret. Store it in your secret manager. Disabling a service account invalidates its keys. Revoking or expiring a key also stops its access. These checks happen on subsequent requests.
Rotate keeps the key’s name and scopes but invalidates its old secret immediately. To switch a running caller without an interruption, create a second key with the same required scopes, install and verify it, then revoke the old key.
Choose scopes
| Scope | Access |
|---|---|
config:read | Workspace configuration, schedules, services and configuration snapshots. |
config:manage | Operational configuration writes; includes config:read. |
incidents:status | Narrow incident status list/detail without raw payloads or responder contact information. |
incidents:read | Incident detail and analytics; includes incidents:status. |
incidents:manage | Supported incident actions; includes incident read/status access. |
status-pages:read | Status-page configuration and supported reads. |
status-pages:manage | Supported status-page management and page publication; includes page reads. It does not authorize authoring customer incident communications. |
Scopes do not cross families: config:manage does not grant incident management.
Some operations require two scopes, such as status-page planned-monitoring pause
and resume, which require status-pages:manage and config:manage.
The API Explorer
describes each operation. The OpenAPI
extension x-warnfire-required-scope names the scope for core machine operations.
GET /v1/tenant/me accepts any valid tenant API key and identifies its effective
scopes. A new endpoint is not automatically available to API keys.
Configure a synthetic workspace
Use a dedicated test workspace and a config:manage key. Choose the API origin
for that workspace: https://api.dev.warnfire.com for development or
https://api.warnfire.com for production. Do not send a development credential
to production. Send requests with Authorization: Bearer <your API key> and
Content-Type: application/json. The placeholder below is not a usable key.
GET /v1/tenant/config/snapshot
Authorization: Bearer <your API key>
Read the snapshot before creating anything. Mutating configuration requests are not a blanket idempotent interface: after a timeout, inspect the snapshot before repeating a create. These examples configure resources; they do not send a test event or prove that a responder can receive notifications.
1. Create a responder
POST /v1/tenant/config/users returns the new responder’s id. Replace the
example address with a mailbox you control if you intend to test email delivery;
the synthetic .invalid address cannot receive mail. Creation alone does not
confirm a notification destination or grant console membership.
{"name":"Automation demo responder","email":"automation-demo@example.invalid","phone":"","sms_consent":false}
2. Create a schedule
POST /v1/tenant/config/schedules returns its id. Replace USER_ID with the
responder ID from step 1. Dates and handoff times are interpreted in the named
timezone. This example starts a daily rotation on October 14, 2026.
{"name":"Automation demo schedule","timezone":"UTC","starts_on":"2026-10-14","handoff_time":"09:00","rotation_length_days":1,"member_user_ids":["USER_ID"]}
3. Create an escalation policy
POST /v1/tenant/config/policies returns its id. Replace SCHEDULE_ID with the
schedule ID. This policy selects email; delivery still requires a confirmed,
eligible email destination.
{"name":"Automation demo policy","steps":[{"position":0,"delay_seconds":60,"condition":"while_unacknowledged","channels":["email"],"schedule_id":"SCHEDULE_ID"}]}
4. Create a service
POST /v1/tenant/config/services returns service_id and its initial integration
credential. Replace POLICY_ID with the policy ID. events binds the credential
to the Events API; choose the documented source for another adapter.
{"name":"Automation demo service","policy_id":"POLICY_ID","source":"events"}
Service creation and key creation/rotation can return a secret once. Capture those responses directly into protected storage rather than shared terminal logs. Snapshot and key-list displays redact existing secrets.
5. Create an additional integration key
POST /v1/tenant/config/services/SERVICE_ID/integration-keys returns the new key
and its id. Replace SERVICE_ID with the service ID. The integration key is
for ingestion on that service; it is not a tenant management credential.
{"name":"Automation demo monitor","source":"events"}
Rotate it with
POST /v1/tenant/config/services/SERVICE_ID/integration-keys/KEY_ID/rotate and
body {"name":"Automation demo monitor"}. Rotation retains its source and
invalidates the previous secret immediately.
Verify it worked
Read GET /v1/tenant/config/snapshot again and verify the responder, schedule,
policy, service and key IDs. To retire the synthetic configuration, delete the
service and policy in that order through their corresponding
/v1/tenant/config/.../ID endpoints. These operations retain historical records.
A schedule referenced by the retained policy cannot be deleted: that request
returns 409. Disable it with PUT /v1/tenant/config/schedules/SCHEDULE_ID,
using its configuration fields from step 2 plus "enabled":false, and replace
member_user_ids with the existing demo responder’s ID. A responder still
referenced by a rotation cannot be disabled, even when the schedule is disabled.
This reassignment changes only the inactive example schedule. Disable the
demo responder with PUT /v1/tenant/config/users/USER_ID, using its fields from
step 1 plus "enabled":false.
Revoke the temporary automation key from the console when finished.
Session-only operations and failures
A tenant API key cannot create, rotate or revoke tenant API keys, manage service accounts or console membership credentials, issue responder tokens, manage billing, or complete interactive provider authorization. These operations require an authorized signed-in session because they create authority, approve spending or require human provider consent. Email/phone confirmation sends and customer-facing status incident communications also retain their session gates.
An invalid, expired or revoked key receives 401. Insufficient scope or a
session-only operation receives 403; a billing restriction or suspension can
block tenant access independently of scopes. Resource IDs are resolved inside
the credential’s workspace; knowing another workspace’s ID does not grant access.
Inspect the response and current account state before retrying. Do not broaden
the key’s scopes to bypass a session-only operation.
Next step
Use the API Explorer to inspect the complete request and response schema for each operation your automation needs.