> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stairoids.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate Your API Requests to the Stairoids API

> Generate API keys, pass them in the Authorization header, understand read and write scopes, and safely rotate credentials for the Stairoids REST API.

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.

<Note>
  The Stairoids REST API base URL is `https://api.stairoids.com/v1`. All endpoints described in this documentation are relative to this base URL.
</Note>

## 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.

<Steps>
  <Step title="Log in to Stairoids">
    Navigate to [app.stairoids.com](https://app.stairoids.com) and sign in with your account credentials.
  </Step>

  <Step title="Open Settings">
    Click **Settings** in the left sidebar.
  </Step>

  <Step title="Navigate to API Keys">
    Select **API Keys** from the Settings sub-menu.
  </Step>

  <Step title="Create a new key">
    Click **New API Key** in the top-right corner of the API Keys panel.
  </Step>

  <Step title="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](#key-scopes) below for guidance.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Making Authenticated Requests

Pass your API key in the `Authorization` header of every request using the `Bearer` scheme.

```http theme={null}
Authorization: Bearer <your-api-key>
```

### Example: cURL

```bash theme={null}
curl -X GET "https://api.stairoids.com/v1/accounts" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"
```

### Example: Node.js (fetch)

```javascript theme={null}
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)

```python theme={null}
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.

<CardGroup cols={2}>
  <Card title="Read-Only" icon="eye">
    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.
  </Card>

  <Card title="Read-Write" icon="pen-to-square">
    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.
  </Card>
</CardGroup>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Error Responses

When authentication fails, the API returns a standard error response with a descriptive message.

<ResponseField name="401 Unauthorized" type="object">
  Returned when the `Authorization` header is missing, malformed, or contains an invalid or revoked API key.

  ```json theme={null}
  {
    "error": "unauthorized",
    "message": "Missing or invalid API key. Provide a valid Bearer token in the Authorization header.",
    "request_id": "req_01HXYZ1234ABCDEF"
  }
  ```
</ResponseField>

<ResponseField name="403 Forbidden" type="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.

  ```json theme={null}
  {
    "error": "forbidden",
    "message": "This API key does not have write access. Generate a Read-Write key to perform this operation.",
    "request_id": "req_01HXYZ5678GHIJKL"
  }
  ```
</ResponseField>

<Note>
  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.
</Note>