# Authentication The Zaphiri Inbox API uses two authentication methods, depending on the type of endpoint. ## Authenticated Endpoints (JWT) All endpoints under `/api/v1/integrations` and `/api/v1/inbox` (management endpoints) require a valid JWT bearer token. ### Authorization Header Include a valid JWT in the `Authorization` header: ``` Authorization: Bearer <your_jwt_token> ``` The JWT must be signed with **HS256** and contain the following claims: | Claim | Type | Required | Description | |-------|------|----------|-------------| | `user_id` | string (UUID) | Yes | The authenticated account's ID | | `token_type` | string | No | Recommended: `"access"`. Not currently enforced but included for forward compatibility. | | `exp` | number | Yes | Expiration time (Unix timestamp) | | `iat` | number | Yes | Issued at time (Unix timestamp) | | `iss` | string | No | Token issuer identifier | ### Token Lifecycle - **Access token lifetime**: set by the main Zaphiri app (usually 1 hour for account tokens, 5 minutes for service-to-service tokens) - **Proactive refresh**: the client refreshes tokens before they expire to avoid interruptions - **Single-flight refresh**: concurrent requests share a single refresh call, preventing race conditions - **401 retry**: if a request returns 401, the client refreshes the token and retries once on its own ### Example Request ```bash curl -X GET https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." ``` ### Authentication Errors **Missing authorization header** ``` HTTP/1.1 401 Unauthorized { "error": "missing authorization header" } ``` **Invalid format** (not `Bearer <token>`) ``` HTTP/1.1 401 Unauthorized { "error": "invalid authorization format" } ``` **Invalid or expired token** ``` HTTP/1.1 401 Unauthorized { "error": "invalid token" } ``` **Token missing user_id claim** ``` HTTP/1.1 401 Unauthorized { "error": "invalid token claims" } ``` ## Team API Endpoints (Integration Token as Bearer) All `/api/v1/team/*` endpoints use an integration token as a Bearer token in the `Authorization` header. It is not a JWT, and it does not go in the URL path. ``` Authorization: Bearer <integration-token> ``` This is the same token used for the webhook Inbox, passed as a Bearer header rather than in the URL. See [[API-Reference/Team|Team API]] for the full endpoint reference. ## Public Endpoints (Integration Token in URL) The webhook receive endpoint (`POST /api/v1/inbox/{token}`) does **not** require JWT authentication. Instead, it uses the integration token directly in the URL path. Integration tokens are generated when you [[API-Reference/Integrations#Create Integration|create an integration]] and can be [[API-Reference/Integrations#Rotate Integration Token|rotated]] at any time. ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/9fbc5ae758ae351091a5a61cdfacfeed02941e490a939112ace299423e39e32c \ -H "Content-Type: application/json" \ -d '{"items": [{"text": "New task from my app"}]}' ``` > [!warning] Keep tokens secret > Integration tokens grant write access to your Inbox. Treat them like API keys: > - Never commit tokens to source control > - Use environment variables or secret managers > - Rotate straight away if a token is compromised, using the [[API-Reference/Integrations#Rotate Integration Token|Rotate Token]] endpoint ### Invalid Token Error ``` HTTP/1.1 401 Unauthorized { "error": "invalid_token" } ``` This error is returned when the token does not match any active integration. ## Endpoint Authentication Summary | Endpoint | Auth Method | |----------|-------------| | `GET /health` | None | | `POST /api/v1/inbox/{token}` | Integration token (in URL) | | `GET /api/v1/integrations` | JWT | | `POST /api/v1/integrations` | JWT | | `GET /api/v1/integrations/{id}` | JWT | | `PUT /api/v1/integrations/{id}` | JWT | | `DELETE /api/v1/integrations/{id}` | JWT | | `POST /api/v1/integrations/{id}/rotate` | JWT | | `GET /api/v1/integrations/{id}/history` | JWT | | `GET /api/v1/integrations/{id}/logs` | JWT | | `POST /api/v1/integrations/{id}/test` | JWT | | `GET /api/v1/inbox` | JWT | | `POST /api/v1/inbox/{id}/convert` | JWT | | `POST /api/v1/inbox/{id}/dismiss` | JWT | | `POST /api/v1/inbox/bulk` | JWT | | `GET /api/v1/team/projects` | Integration token (Bearer) | | `POST /api/v1/team/projects` | Integration token (Bearer) | | `PUT /api/v1/team/projects/{id}` | Integration token (Bearer) | | `DELETE /api/v1/team/projects/{id}` | Integration token (Bearer) | | `GET /api/v1/team/projects/{id}/settings` | Integration token (Bearer) | | `PUT /api/v1/team/projects/{id}/settings` | Integration token (Bearer) | | `GET /api/v1/team/projects/{id}/tasks` | Integration token (Bearer) | | `POST /api/v1/team/projects/{id}/tasks` | Integration token (Bearer) | | `GET /api/v1/team/tasks/{id}` | Integration token (Bearer) | | `PUT /api/v1/team/tasks/{id}` | Integration token (Bearer) | | `PATCH /api/v1/team/tasks/{id}` | Integration token (Bearer) | | `DELETE /api/v1/team/tasks/{id}` | Integration token (Bearer) | | `POST /api/v1/team/tasks/{id}/append` | Integration token (Bearer) | | `POST /api/v1/team/tasks/{id}/branch` | Integration token (Bearer) | | `POST /api/v1/team/tasks/{id}/comments` | Integration token (Bearer) | | `POST /api/v1/team/tasks/{id}/subtasks` | Integration token (Bearer) | | `GET /api/v1/team/notifications` | Integration token (Bearer) | --- **Next:** Manage your integrations with [[API-Reference/Integrations|Integrations]]