Authentication
Authenticate Stacksync API requests with a workspace API key or a user API key in the Authorization header
Every request carries one API key, as a bearer token in the Authorization header:
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,PUTandPATCHrequests must sendContent-Type: application/json.- Most answers carry an
X-Request-Idheader. 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 |
{ "error": "Invalid API Key", "msg": "The API Key provided in the request is invalid" }See 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 and sign in as the person using them. See MCP authentication.