Authentication Overview
Orqio supports authenticated API access for organization and workspace resources.
Supported authentication methods
The Orqio API supports multiple authentication mechanisms (availability varies per endpoint; consult the API reference):
- User auth (JWT): send
Authorization: Bearer <token> - Cookie-based auth (browser use cases):
access_tokencookie - API keys (server-to-server): send either:
x-api-key: pk_...Authorization: Bearer pk_...
API keys are workspace-scoped and created in the Orqio UI. See API Keys.
You can see security scheme details in the API reference introduction: API Reference.
Choosing the right pattern
- Use JWT/cookie auth for user-driven operations and endpoints requiring user identity.
- Use API keys for backend service integrations on supported endpoints.
| Scenario | Recommended auth |
|---|---|
| User signed in to Orqio UI | JWT / cookie |
| Backend sync job calling contacts API | API key |
| Automation requiring user permissions | JWT |
Treat credentials as secrets
Never commit tokens/keys into Git or paste them into tickets. Store them in a secret manager and rotate regularly.
Operational recommendations
- Store credentials in a managed secret store.
- Rotate keys regularly and remove unused credentials.
- Scope access by organization and workspace boundaries.
Troubleshooting
- 401 Unauthorized usually means your credential is missing/invalid/expired.
- 403 Forbidden usually means your credential is valid but lacks access to the org/workspace or resource.
- If you see an error stating API keys are only supported on contacts endpoints, you’re calling an endpoint that requires user authentication (JWT/cookie).
When contacting support, include the X-Request-Id response header if available (see API Conventions).