Authentication
Every request to the Incapon API is authenticated with an API key belonging to your team. The key is sent as a Bearer token in the Authorization header; there are no sessions, cookies or OAuth flows. Which team the key belongs to, which tools it can reach and which balance it spends from are all derived from the key itself.
Creating and using a key
Keys are created per team under Settings β API Keys. Only the team owner and admins can create keys. The full value is shown once at creation; afterwards the dashboard only shows its last four characters.
curl https://api.incapon.com/v2.4/credits/balance \ -H "Authorization: Bearer $INCAPON_API_KEY"
Always keep the key in an environment variable such as INCAPON_API_KEY or in a secrets manager. The official SDKs read this variable automatically.
Test and live keys
| Prefix | Environment | Spends credits | Sends webhooks |
|---|---|---|---|
| inc_test_... | Test | No | Yes |
| inc_live_... | Live | Yes | Yes |
Test keys do not run real jobs; they return responses of the same shape filled with sample data and send webhook events as if they were real. That lets you exercise your integration end to end without spending balance. Going live only means swapping the key.
Scopes and IP restrictions
Each key is given scopes when it is created: detector, pdf, signature, transcribe and credits:read. A request to an endpoint outside the key's scopes returns 403 FORBIDDEN. For integrations running from a server you can also add allowed IP ranges to the key; requests from outside the list get 403 too. Giving each integration its own key with only the scopes it needs limits the damage if one leaks.
Rotating a key
To rotate a key, create a new one, deploy it to your application, then shut the old one down with Revoke. Since two keys can be valid at the same time, there is no downtime. The "last used" column in the dashboard shows whether the old key still receives traffic.
If a key ends up in a repository, client-side code or a log file, revoke it without waiting. Revocation takes effect instantly, and further requests with that key get 401 UNAUTHORIZED.
Rate limit
Each key can send up to 600 requests per minute. Every response carries the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. When the limit is exceeded the API returns 429 and the Retry-After header tells you how many seconds to wait. For a retry strategy, see Error Codes.