# 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]]