Skip to main content
Every request to the Stairoids REST API must include a valid API key in the Authorization header. There are no session cookies, OAuth flows, or IP allowlists required — your API key is the single credential that identifies your integration and determines what actions it can perform. Keys are scoped to specific permission levels, so you can issue narrow-purpose keys for read-only integrations without exposing write access.

​
Generating an API Key

You create and manage API keys from the Stairoids dashboard. Each key is shown only once at creation time — copy it immediately and store it somewhere safe.
1

Open API Keys settings

In the Stairoids dashboard, navigate to Settings → API Keys.
2

Create a new key

Click New API Key. Give the key a descriptive name (e.g., production-signal-ingest or staging-read-only) and select the appropriate scope.
3

Copy and store the key

Your new key is displayed once. Copy it immediately and store it in a secrets manager or environment variable. Stairoids does not show the full key again after this step.
For a full walkthrough of the API Keys UI including rotation and revocation, see the Authentication configuration guide.

​
Key Scopes

Every API key is issued with one of three scopes. Choose the most restrictive scope that satisfies your integration’s needs — this limits the blast radius if a key is ever compromised.
ScopePermitted MethodsTypical Use Case
readGET onlyAnalytics dashboards, audit scripts, read-only integrations
writePOST, PATCH, DELETESignal ingestion pipelines, webhook management, data writes
read_writeAll methodsFull-access integrations, internal tooling

​
Attaching the Authorization Header

Pass your API key as a Bearer token in the Authorization header on every request. No additional headers are required for authentication. 
curl https://api.stairoids.com/v1/signals \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"
Never expose your API key in client-side code, public repositories, or anywhere it could be accessed by unauthorized parties. Always load keys from environment variables or a secrets manager at runtime, and add key patterns to your .gitignore and secret-scanning rules.
Use the Name field when generating a key to embed the environment prefix — for example, sk_live_ for production keys and sk_test_ for testing keys. Consistent naming makes it immediately clear which key a log entry or error came from, and reduces the risk of accidentally using a production key in a staging pipeline.

​
Authentication Error Responses

When authentication fails, the API returns a structured error response. Use the error.code field to handle each case programmatically.
Returned when the Authorization header is absent, incorrectly formatted, or the key has been revoked.
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required. Provide it as 'Authorization: Bearer <key>'."
  },
  "meta": {
    "request_id": "req_err401abc"
  }
}
How to fix: Confirm that your request includes the header Authorization: Bearer <your-key> with no extra spaces or encoding issues, and that the key has not been revoked in Settings → API Keys.
Returned when the API key is valid and active but does not have the scope required by the endpoint you are calling.
{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have the 'write' scope required for this endpoint.",
    "param": "scope"
  },
  "meta": {
    "request_id": "req_err403xyz"
  }
}
How to fix: Generate a new key with the write or read_write scope, or update your integration to use an existing key that has the required permissions.