# Authentication

> Authenticate Stacksync API requests with a workspace API key or a user API key in the Authorization header

Source: https://docs.stacksync.com/api-reference/authentication

Every request carries one API key, as a bearer token in the `Authorization` header:

```bash
curl https://api.stacksync.com/v1/workspaces \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"
```

## API keys

| Key               | Starts with  | Created by                                                      | Acts with                                            |
| ----------------- | ------------ | --------------------------------------------------------------- | ---------------------------------------------------- |
| Workspace API key | `workspace_` | A workspace owner, under **Workspace settings > Stacksync API** | Editor rights, on its own workspace only             |
| User API key      | `user_`      | Any member, under **Profile > Stacksync API**                   | The user's own role in each workspace they belong to |

Use a workspace API key for an integration that serves one workspace. Use a user API key when the integration acts for one person, in every workspace they belong to: it can do what that person can do in the app.

## Requests

* Send the key in the `Authorization: Bearer <key>` header only. Never put it in a URL, and never ship it in client-side code such as a browser app or a mobile app.
* `POST`, `PUT` and `PATCH` requests must send `Content-Type: application/json`.
* Most answers carry an `X-Request-Id` header. Quote it when you contact support about a request.

## Authentication errors

An authentication or permission failure always answers **403**, never 401. The `error` field names the cause:

| `error`                 | Cause                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Invalid API Key`       | The key is invalid, the workspace in the URL is not the key's workspace, or the key's user is not a member of that workspace                         |
| `Authorization Error`   | The `Authorization` header is missing or is not `Bearer <key>`                                                                                       |
| `Authentication Error`  | Your role in the workspace does not allow the operation (for example, a viewer's user API key on a change), or the resource is not in this workspace |
| `Insufficient Scope`    | A read-only sign-in tried to change something                                                                                                        |
| `Workspace Unavailable` | The workspace has been deleted                                                                                                                       |
| `Content-Type Error`    | A `POST`, `PUT` or `PATCH` request did not send `Content-Type: application/json`                                                                     |

```json
{ "error": "Invalid API Key", "msg": "The API Key provided in the request is invalid" }
```

See [Errors](/api-reference/errors) for every other status.

## Keep keys safe

* Store keys in a secret manager or your platform's encrypted environment variables, never in source control.
* To rotate a key, regenerate it in the Stacksync app where it was created, then update the integrations that use it.

## AI assistants

AI assistants such as Claude, ChatGPT or Cursor don't need an API key: they connect to the [Stacksync MCP](/mcp) and sign in as the person using them. See [MCP authentication](/mcp/authentication).