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

# Authentication

> Authenticate with StackOne APIs using API keys and Basic Auth

All StackOne APIs use **Basic Auth** with your API key as username and an empty password.

***

## Get Your API Key

1. Go to <a href="https://app.stackone.com/api_keys" target="_blank">**Configuration → API Keys**</a> in the dashboard
2. Click **Create API Key** and copy it securely

<Warning>
  API keys are shown only once. Store securely in a password manager or environment variable.
</Warning>

<Tip>
  For detailed steps with screenshots, see the [API Keys Guide](/guides/api-keys).
</Tip>

***

## Using Your API Key

All StackOne APIs use **Basic Auth** with your API key as username and empty password.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # -u flag auto-encodes to base64
    curl -u "$STACKONE_API_KEY:" https://api.stackone.com/accounts
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const encoded = Buffer.from(`${apiKey}:`).toString('base64');
    fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import base64
    encoded = base64.b64encode(f"{api_key}:".encode()).decode()
    headers = {'Authorization': f'Basic {encoded}'}
    ```
  </Tab>
</Tabs>

<Tip>
  Get your API key from <a href="https://app.stackone.com/api_keys" target="_blank">**Configuration → API Keys**</a> in the dashboard.
</Tip>

***

## Account ID Header

For APIs that operate on a linked account, include the `x-account-id` header:

<Tabs>
  <Tab title="Get Account">
    ```bash theme={null}
    curl -u "$API_KEY:" \
      -H "x-account-id: your-account-id" \
      https://api.stackone.com/accounts/your-account-id
    ```
  </Tab>

  <Tab title="Execute Action">
    ```bash theme={null}
    curl -X POST -u "$API_KEY:" \
      -H "x-account-id: your-account-id" \
      -H "Content-Type: application/json" \
      https://api.stackone.com/actions/rpc \
      -d '{"action": "google_drive_list_files", "query": {}}'
    ```
  </Tab>
</Tabs>

<Note>
  Get account IDs from the [List Accounts](/platform/api-reference/accounts/list-accounts) endpoint or the <a href="https://app.stackone.com/accounts" target="_blank">**Accounts**</a> page in the dashboard.
</Note>

***

## API Key Scopes

| Scope           | Access                   |
| --------------- | ------------------------ |
| **Full Access** | All operations (default) |
| **Read Only**   | GET requests only        |
| **Accounts**    | Account management       |
| **Actions**     | Action execution via RPC |

<Info>
  Fine-grained scopes are an add-on feature. Contact your account manager for access.
</Info>

***

## Base URL

```
https://api.stackone.com
```

| API      | Pattern                                    |
| -------- | ------------------------------------------ |
| Platform | `/accounts`, `/actions/rpc`, `/connectors` |
| Unified  | `/unified/{category}/{resource}`           |
| MCP      | `/mcp`                                     |

***

## Error Responses

| Code  | Meaning                      |
| ----- | ---------------------------- |
| `401` | Invalid or missing API key   |
| `403` | API key lacks required scope |
| `404` | Invalid account ID           |
| `412` | Account suspended or expired |

<Tip>
  For all error codes including rate limits (429), timeouts (408), and provider errors (502), see the [Error Codes Guide](/guides/unified-api-error-codes-and-troubleshooting-guide).
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Keys Guide" icon="key" href="/guides/api-keys">
    Create, scope, and manage API keys
  </Card>

  <Card title="Basic Auth Guide" icon="lock" href="/basic-authentication-with-stackone-api">
    Detailed encoding examples and SDK usage
  </Card>
</CardGroup>