Authenticate Your Requests to the Stairoids API

Stairoids uses an API key to authenticate every request to the public REST API. There are no session cookies or OAuth flows for server-to-server communication — just a long-lived secret key that you send in a single HTTP header. This keeps integration code simple and portable across any language or platform.

The public API base URL is https://app.stairoids.com/api, and all endpoints in this documentation live under https://app.stairoids.com/api/public/v1. The public API is read-only — it exposes the scored data Stairoids computes for your organization.

Generating an API Key

Your organization has a single public API key. Generate or view it from the Stairoids dashboard.

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

Open Settings

Click Settings in the left sidebar.

Find your public API key

Open the API section. If your organization doesn’t have a key yet, generate one.

Copy and store the key securely

Copy the key immediately and store it in a secrets manager, environment variable, or password vault.

Treat your API key like a password. Store it in a tool like AWS Secrets Manager, HashiCorp Vault, or a .env file excluded from version control. If a key is exposed, rotate it (see Rotating Keys) — rotating immediately invalidates the old value.

Making Authenticated Requests

Pass your API key in the X-Api-Key header of every request. Do not use an Authorization: Bearer header — that scheme isn’t used by the Stairoids API.

X-Api-Key: <your-api-key>

Example: cURL

curl -X GET "https://app.stairoids.com/api/public/v1/funnel/stages" \
  -H "X-Api-Key: YOUR_API_KEY"

Example: Node.js (fetch)

const response = await fetch(
  "https://app.stairoids.com/api/public/v1/funnel/stages",
  {
    method: "GET",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
    },
  }
);

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

Example: Python (requests)

import requests

headers = {
    "X-Api-Key": "YOUR_API_KEY",
}

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

For POST endpoints, also send Content-Type: application/json with your JSON body.

Key Scope

The public API key is scoped to your organization and grants read access to your organization’s data. There are no per-key permission scopes to choose — a single key works across every endpoint in this reference, and no endpoint creates, updates, or deletes data.

Rotating Keys

Rotate your API key periodically — or immediately after a suspected compromise. Because each organization has one key, rotation replaces the current value.

Regenerate the key

In Settings → API, regenerate your public API key. This issues a new value and immediately invalidates the old one.

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 so they pick up the new key.

Verify the new key is working

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

Rotate on a regular schedule, and keep the new key in a secrets manager so every service reads it from one place — rotating then means updating a single value rather than hunting down hardcoded copies.

Error Responses

Authentication failures return a 401. Other errors — bad input, or a resource that isn’t in your pipeline — return a 4xx with a small JSON body carrying a machine-readable errorType.

object

Returned when the X-Api-Key header is missing, empty, or not a valid key for any organization. The request is rejected by the API’s security layer before it reaches an endpoint, so a 401 carries no errorType body.

All API errors use the same shape — a single errorType field with a machine-readable code (for example NOT_FOUND or VALIDATION_ERROR). Business and validation errors return 400; a resource that isn’t in your pipeline also returns 400 with errorType: NOT_FOUND (there is no 404).

Get Started

Signals

Integrations

Configuration

Resources

Authenticate Your Requests to the Stairoids API

Generating an API Key

Making Authenticated Requests

Example: cURL

Example: Node.js (fetch)

Example: Python (requests)

Key Scope

Rotating Keys

Error Responses

​Generating an API Key

​Making Authenticated Requests

​Example: cURL

​Example: Node.js (fetch)

​Example: Python (requests)

​Key Scope

​Rotating Keys

​Error Responses

Generating an API Key

Making Authenticated Requests

Example: cURL

Example: Node.js (fetch)

Example: Python (requests)

Key Scope

Rotating Keys

Error Responses