Skip to main content
Stairoids uses API keys to authenticate every request you make to the REST API. There are no session cookies or OAuth flows for server-to-server communication — just a long-lived secret key that you include in a standard HTTP header. This keeps integration code simple and portable across any language or platform.
The Stairoids REST API base URL is https://api.stairoids.com/v1. All endpoints described in this documentation are relative to this base URL.

​
Generating an API Key

Create a new API key from the Stairoids dashboard. You can create as many keys as you need — one per integration is the recommended practice.
1

Log in to Stairoids

Navigate to app.stairoids.com and sign in with your account credentials.
2

Open Settings

Click Settings in the left sidebar.
3

Navigate to API Keys

Select API Keys from the Settings sub-menu.
4

Create a new key

Click New API Key in the top-right corner of the API Keys panel.
5

Name your key and choose a scope

Enter a descriptive name (e.g., hubspot-integration or zapier-readonly) and select either Read-only or Read-Write scope. See Key Scopes below for guidance.
6

Copy and store the key securely

Your new key is displayed once. Copy it immediately and store it in a secrets manager, environment variable, or password vault. Click Done to close the dialog.
API keys are shown only once at creation time. Stairoids does not store a recoverable copy. If you lose a key, you must revoke it and generate a new one. Store your keys securely in a tool like AWS Secrets Manager, HashiCorp Vault, or a .env file excluded from version control.

​
Making Authenticated Requests

Pass your API key in the Authorization header of every request using the Bearer scheme. 
Authorization: Bearer <your-api-key>

​
Example: cURL

curl -X GET "https://api.stairoids.com/v1/accounts" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

​
Example: Node.js (fetch)

const response = await fetch("https://api.stairoids.com/v1/accounts", {
  method: "GET",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

​
Example: Python (requests)

import requests

headers = {
    "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
}

response = requests.get("https://api.stairoids.com/v1/accounts", headers=headers)
data = response.json()
print(data)

​
Key Scopes

When generating an API key, choose the scope that matches the integration’s actual needs. Follow the principle of least privilege — give each key only the access it requires.

Read-Only

Allows GET requests only. Use this scope for dashboards, reporting tools, and any integration that needs to pull data from Stairoids without writing signals or triggering automations. Read-only keys cannot create, update, or delete any resource.

Read-Write

Allows all HTTP methods: GET, POST, PUT, PATCH, and DELETE. Use this scope for integrations that send signals to Stairoids, manage automations, or update account and contact records. Most server-side integrations require Read-Write access.

​
Rotating Keys

Rotating API keys periodically — or immediately after a suspected compromise — is a security best practice. Follow this zero-downtime rotation procedure to avoid interrupting active integrations.
1

Generate a new API key

In Settings → API Keys, click New API Key. Give it the same name as the key you’re replacing with a version suffix (e.g., hubspot-integration-v2) and select the same scope.
2

Update your integrations

Replace the old key value with the new one in every integration, environment variable, or secrets manager entry that references it. Deploy or restart the affected services to pick up the new key.
3

Verify the new key is working

Make a test API call using the new key and confirm you receive a 200 OK response before proceeding.
4

Revoke the old key

Back in Settings → API Keys, click the ⋯ menu next to the old key and select Revoke. Confirm the revocation. The old key is immediately invalidated — any requests still using it will receive a 401 Unauthorized response.
Use separate API keys for each integration so you can revoke individual access without affecting others. For example, if your Zapier integration is compromised, you can revoke only that key while your HubSpot and Segment integrations continue working uninterrupted.

​
Error Responses

When authentication fails, the API returns a standard error response with a descriptive message.
​
401 Unauthorized
object
Returned when the Authorization header is missing, malformed, or contains an invalid or revoked API key.
{
  "error": "unauthorized",
  "message": "Missing or invalid API key. Provide a valid Bearer token in the Authorization header.",
  "request_id": "req_01HXYZ1234ABCDEF"
}
​
403 Forbidden
object
Returned when the API key is valid but lacks the required scope for the requested operation. For example, using a Read-only key to create a signal returns this error.
{
  "error": "forbidden",
  "message": "This API key does not have write access. Generate a Read-Write key to perform this operation.",
  "request_id": "req_01HXYZ5678GHIJKL"
}
Every API error response includes a request_id field. Keep this value handy — Stairoids support can use it to look up the exact request when investigating an issue. Include it in any support ticket you raise.