> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/authentication-bearer-tokens-and-personal-api-keys.md).

# Authentication: Bearer Tokens and Personal API Keys

Use a personal API key for a backend integration. Send it in `Authorization: Bearer <personal-api-key>` for the REST examples. Bearer is a header scheme, not a separate kind of credential: supported endpoints can use either a personal key or a user access token in that header. Legacy inference and analytics have different credential restrictions.

![Authenticate from your backend](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FmkewvRcbO5YTJ1RzVQbb%2Fauthentication-bearer-tokens-and-personal-api-keys.png?alt=media)

Two supported header forms for v2 runs. Set STACKAI\_BASE\_URL to your deployment’s documented API base URL. Legacy inference requires the Authorization form.

<details>

<summary>Copy the example</summary>

```bash
# Load STACKAI_API_KEY from your secret manager.
curl "$STACKAI_BASE_URL/v2/runs/$RUN_ID" \
  -H "Authorization: Bearer $STACKAI_API_KEY"

# Alternative accepted by the v2 run endpoints:
curl "$STACKAI_BASE_URL/v2/runs/$RUN_ID" \
  -H "X-API-Key: $STACKAI_API_KEY"

# Choose one header. Keep the key out of browser code.
```

</details>

## Before you begin

A valid credential with the required permissions and resource access.

## Authentication methods

| Term                  | Definition                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication        | Verification of the account or credential making a request. It identifies the caller but does not grant every resource permission.                                        |
| Bearer authentication | An Authorization header whose value begins with Bearer followed by a supported credential. Anyone possessing the credential may be able to use it within its permissions. |
| X-API-Key             | A header accepted by supported routes for a raw personal API key. Do not add a Bearer prefix inside this header value.                                                    |
| API key               | A secret credential accepted by a supported API or connector. Send it only through the documented authentication field or header.                                         |
| Access token          | A credential used to authorize requests for its valid lifetime. Expiration or revocation can prevent an otherwise valid operation.                                        |

## Authenticate an API request

1. Create a personal key in **Settings → API Keys** in the organization containing the resource. Give it only the scopes needed by your application.
2. Send the key through `Authorization: Bearer` over HTTPS. Keep it in your backend; do not put it in browser code.
3. Call an operation allowed by both the key scopes and its owner’s current access. For a workflow run, the key needs `projects.run`; reading its result also needs `analytics.read`.
4. For a 401, check the credential and expiry. For a 403, check scope and resource access. Do not retry an unchanged rejected credential.

The request is authenticated as the intended account or key.

## Behavior and limitations

The `/v2/runs` operations also accept `X-API-Key` for a personal key. Legacy `/inference/v0/...` and `/analytics/org/...` routes require the Authorization form. For endpoints supporting X-API-Key, send the raw key as its value. Do not prefix that header value with Bearer. Personal keys can also use Authorization: Bearer on supported routes. Older routes can require the Authorization form. Do not send conflicting credentials in multiple headers.

```http
Authorization: Bearer <access-token-or-supported-personal-key>
```

Or, where supported:

```http
X-API-Key: <personal-api-key>
```

## Related resources

API Versions and Compatibility

[API authentication and endpoint restrictions](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/authentication-and-authorization.md)

[Run your first workflow through the API](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/quickstart.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/authentication-bearer-tokens-and-personal-api-keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
