Authentication
The Upstat API uses JWT-based API tokens for authentication. All API requests must include a valid token in the Authorization header.
API Tokens
API tokens provide secure, programmatic access to the Upstat API. Tokens are account-scoped with configurable permissions per resource. Only account owners can create and manage API tokens.
Creating an API Token
- Navigate to Settings > API in your Upstat dashboard
- Click Create API Token
- Enter a descriptive name for the token
- Select an expiration period (or choose “Never”)
- Configure the permissions for each resource
- Click Save to generate your token
Tip: You can reveal your token anytime by clicking the eyeball icon on the token detail page.
Token Permissions
Each token has granular CRUD permissions for these resources:
| Resource | Description | Example Endpoints |
|---|---|---|
| Monitors | Monitor configurations and check results | GET /monitors, POST /monitors |
| Incidents | Incident management and updates | GET /incidents, PATCH /incidents/:id |
| Heartbeats | Heartbeat monitors and pings | GET /heartbeats, POST /heartbeats/:id/ping |
| Catalog | Service catalog and dependencies | GET /catalog, POST /catalog |
| On-Call | On-call schedules and rotations | GET /on-call, PATCH /on-call/:id |
| Runbooks | Runbook documentation and procedures | GET /runbooks, POST /runbooks |
| Status Pages | Status page configurations | GET /status-pages, PATCH /status-pages/:id |
| Maintenance | Maintenance windows and schedules | GET /maintenance, POST /maintenance |
Permission levels:
| Permission | Description | HTTP Methods |
|---|---|---|
| Read | View resources | GET |
| Create | Create new resources | POST |
| Update | Modify existing resources | PATCH |
| Delete | Remove resources | DELETE |
By default, new tokens have Read enabled for all resources. Enable additional permissions as needed.
Token Expiration
When creating a token, select an expiration period:
| Option | Use Case |
|---|---|
| Never | Long-running production integrations |
| 30 days | Short-term projects or testing |
| 60 days | Medium-term integrations |
| 90 days | Quarterly rotation policy |
| 1 year | Annual rotation policy |
Expired tokens are automatically rejected with a 401 status. Plan to rotate tokens before expiration.
Managing Tokens
From Settings > API, you can:
- View tokens - See all tokens with name, creation date, expiration, and last used
- Edit permissions - Update name and permissions for existing tokens
- Reveal token - View the full JWT token value
- Regenerate - Create a new token value (invalidates the old one)
- Delete - Permanently remove a token
Making Authenticated Requests
Include your API token in the Authorization header using the Bearer scheme:
Error Responses
Authentication failures return error responses in the standard format:
401 - Invalid or Missing Token:
403 - Insufficient Permissions:
Common causes:
| Error | Cause | Solution |
|---|---|---|
authentication_error | Missing or malformed Authorization header | Include Bearer <token> in header |
authentication_error | Invalid token value | Check token was copied correctly |
authentication_error | Expired token | Regenerate or create new token |
permission_error | Token lacks required permission | Edit token to add permission |
Security Best Practices
| Practice | Description |
|---|---|
| Use environment variables | Never commit tokens to version control |
| Minimal permissions | Only enable permissions your integration needs |
| Set expiration | Use expiration for temporary or test integrations |
| Rotate regularly | Regenerate production tokens on a schedule |
| Delete unused tokens | Remove tokens that are no longer needed |
| Monitor usage | Check “Last Used” to identify inactive tokens |
| Separate environments | Use different tokens for dev/staging/production |