Auth methods
- Personal access tokens (PAT) — fastest for server-to-server integrations.
- OAuth apps — best when acting on behalf of a user.
- Webhook signing - authenticate inbound events from Stavent.
Warning
Treat tokens like passwords. Rotate them regularly and store them in your secret manager.
Scopes
Scopes limit what a token can do. Create narrow tokens for each integration and avoid “god tokens”.
| Scope | Allows |
|---|---|
| tickets:read | Read ticket metadata and transcripts. |
| tickets:write | Create, update, and close tickets. |
| audit:read | Read audit log events. |
| webhooks:manage | Create and rotate webhook endpoints. |
Rate limits
The API returns rate limit info via headers:
Rate limit headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1735516800Errors
Errors are returned with an error object and a stable code you can key on.
Error payload
{
"error": {
"code": "invalid_request",
"message": "Missing required field: priority",
"requestId": "req_01H..."
}
}