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

# Authentication

> Authenticate v1 requests with a team-scoped API key, or MCP with a connection key.

v1 endpoints accept an API key in the `Authorization` header. MCP endpoints use a different credential and reject keys sent in the query string.

## Create an API key

**1. Open the dashboard**

Sign in at [statusstack.com/dashboard](https://statusstack.com/dashboard) and switch to the team the key should access.

**2. Create the key**

Go to **Settings** → **API Keys** and create a key with the permissions you need.

**3. Copy it immediately**

The secret is shown once. Store it in an environment variable or a secret manager — never in source control or client-side code.

You can also create and revoke keys through the **API Keys** endpoints in this reference once you already have a key.

## Send the key

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://statusstack.com/api/v1/stacks
```

```javascript JavaScript theme={null}
const response = await fetch("https://statusstack.com/api/v1/stacks", {
  headers: { Authorization: `Bearer ${process.env.STATUSSTACK_API_KEY}` },
});
```

```python Python theme={null}
import os
import requests

requests.get(
    "https://statusstack.com/api/v1/stacks",
    headers={"Authorization": f"Bearer {os.environ['STATUSSTACK_API_KEY']}"},
)
```

## Permissions

Each key can grant one or more of:

| Permission | Allows |
| - | - |
| `read` | GET requests |
| `write` | POST and PUT (includes creating and updating resources) |
| `delete` | DELETE |
| `admin` | Administrative access to all resources |
| `*` | All actions |

A missing or invalid key returns `401` with `{ "error": "..." }`. A valid key without the required permission returns `403`.

v1 keys can only call v1 endpoints. v2 keys can call v1 and v2.

## Team scope

Most v1 operations require a **team-scoped** key. Unscoped keys are rejected with `403` rather than falling back to a session team.

* Create a key while you are in the team you want to automate.
* Multi-team organizations need a key per team.
* Switching teams in the dashboard does not change an existing key's scope.

On stack detail routes, a stack that belongs to another team is returned as `404`, not `403`, so a scoped key cannot probe for stacks it cannot see.

## MCP credentials

MCP routes (`/v1/mcp/*`) do **not** accept a normal v1 API key. Use one of:

* An MCP connection key (`mcp_sk_...`) created in the customer dashboard, sent as `Authorization: Bearer` or `X-API-Key`
* An OAuth 2.1 access token with the `mcp:use` scope

A refused MCP request returns `401` and a `WWW-Authenticate` header pointing at protected-resource metadata so OAuth clients can discover the authorization server.

> [!WARNING]
>
> Never put MCP credentials in the query string. The server ignores them there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.