Authentication
Every request to the Stacked API must include a valid API key. The key determines which organization's data you are operating on — no separate org ID parameter is needed.
X-API-Key header
Pass your API key as the X-API-Key header. This is the recommended approach.
Authorization header
You can also pass the key using the Authorization header with the ApiKey scheme:
Both headers behave identically. X-API-Key is the canonical recommendation.
How keys work
- API keys are org-scoped — one key per organization.
- Keys are issued through the Stacked web app at Settings → API.
- The key is only visible at creation or regeneration. It cannot be retrieved after that, so copy it immediately.
Error responses
All authentication failures return 401:
| Scenario | Message |
|---|---|
| Missing or malformed key | Invalid token format |
| Key doesn't exist or was regenerated | Invalid API key |
| User associated with key not found | No User found that matches that API key |
Legacy JWT flow
The /api/login and /api/refresh endpoints exist for exchanging an API secret for short-lived JWT tokens. This flow is supported but not the recommended path for new integrations — use X-API-Key instead.