Authentication
Every request is authenticated with a bearer token in the Authorization header:
GET /api/ext/v1/me HTTP/1.1
Host: app.jecheck.io
Authorization: Bearer jck_live_xxxxxxxxxxxxxxxx
Requests without a valid token get 401 unauthorized. Tokens must never be sent in query strings.
Token types
| Prefix | Type | Acts as | Created in | Best for |
|---|---|---|---|---|
jck_live_ |
Company key | A service user with the roles and locations chosen for the key | API & MCP → Company keys (permission Company API keys) | Server-to-server integrations: ERP, BI, payroll, bots |
jck_pat_ |
Personal token | You, with your own permissions | API & MCP → My tokens (permission Personal API tokens & AI apps) | Scripts, prototypes, MCP in Cursor / Claude Desktop |
jck_oat_ |
OAuth token | The user who approved the connection | Issued automatically to AI apps | claude.ai, ChatGPT and other MCP clients — see OAuth |
Company keys and permissions
A company key is backed by a service user that cannot sign in to the web or mobile app. Its permissions are exactly the permissions of the roles you pick, on the locations you pick — the same permission model the jeCheck UI uses. So a key with the role Auditor on two locations sees audits of those two locations only, and it is impossible to grant a key more than you have yourself.
Things the key creates or changes are attributed to the service user (shown as API: <key name> in history), so you always know what came from an integration.
Note "Full access" keys act as an administrator. Only administrators can create them; use them sparingly.
Scopes
| Scope | Allows |
|---|---|
read |
All GET endpoints the key's permissions allow |
write |
Creating, changing and deleting (includes read) |
A read-only token calling a write endpoint gets 403 insufficient_scope. MCP clients with a read-only token simply don't see write tools.
Plan
API and MCP access is part of the Enterprise plan. On other plans every call returns 403 plan_required. Some endpoints additionally need a paid feature of the plan (HACCP, testing, mystery shopping…) — the reference marks them with plan feature.
Lifetime and rotation
- Company keys and personal tokens live until revoked or until the optional expiry date.
- To rotate, create a new key, switch your integration, then revoke the old one. Revocation is immediate.
- OAuth access tokens live 1 hour and are refreshed with a refresh token (30 days, rotated on every use).
- Each key shows last used time, IP and request count; the call log keeps 30 days of requests.
Checking what a token can do
GET /me returns the acting user, the token kind and scopes, and every permission with its locations. Call it at start-up and fail fast if something is missing.
Security checklist
- Store tokens in a secrets manager or environment variables, never in code or front-end bundles.
- Give each integration its own key with the narrowest roles, locations and the
readscope where possible. - Set an expiry date for temporary integrations.
- Revoke keys you no longer use — API & MCP → Company keys lists them all.