Appearance
Token management and legacy endpoints
Token management
GET /api/v1/tokens and POST /api/v1/tokens require an authenticated ADMIN or OWNER browser session. An integration bearer token cannot manage tokens. Use Settings → API Access for normal token administration.
GET returns { tokens: [...] } with id, label, maskedToken, status, createdAt, createdBy (id, name), lastUsedAt, and requestCount. It never returns existing secrets.
POST creates a token. It also requires a same-origin Origin or Referer header and Content-Type: application/json:
json
{"label":"HR reporting","fieldAllowlist":["personal_email","phone"]}label must be a nonempty string. fieldAllowlist is optional; see supported employee fields. HTTP 201 returns { token, secret }. Copy secret immediately; it cannot be retrieved later. Missing label or invalid JSON returns 400; insufficient role or invalid/missing origin returns 403. An unauthenticated browser request follows the application's login behavior.
For an authenticated same-origin browser client:
js
const response = await fetch('/api/v1/tokens', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({label: 'HR reporting', fieldAllowlist: ['phone']})
});
const {token, secret} = await response.json();Revoke a token
POST /api/v1/tokens/{tokenId}/revoke
Requires the same admin/owner session and same-origin protections as creation. No body is required. Returns HTTP 200 with {"revoked":true}. A missing or already revoked token returns 404. Requests using that integration token subsequently receive 401.
js
await fetch('/api/v1/tokens/TOKEN_ID/revoke', {method: 'POST'});Legacy employee track
POST /api?action=employee-track
Authenticates with the organisation API key, rather than an API Access integration token. Ask the organisation owner for this legacy credential.
bash
curl -X POST 'https://YOUR-INSTANCE/api?action=employee-track' \
-H 'Authorization: Bearer ORGANISATION_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"first_name":"Alex","last_name":"Example","email":"alex@example.com","team":"Engineering"}'first_name and last_name must be nonempty, and email must be valid. team is optional and defaults to Default Team. Existing employee records return their track link. Otherwise the endpoint creates or reuses an invitation and prepares a track. Success is HTTP 200 with {"redirect_url":"https://YOUR-INSTANCE/dashboard/employee/ID/track"}. The ID may be an invitation ID. Validation returns 400, invalid authentication 401, plan restrictions 403, and a missing organisation owner 404.
POST /api?action=admin-login is retired and returns 403 after organisation authentication. Integration credentials cannot create browser sessions.
Legacy completion callback
POST /api/callbacks/tasks/{taskId}/complete
This older endpoint requires server-side TASK_CALLBACK_SECRET configuration and a trusted organisation context supplied by the deployment. Authenticate using Authorization: Bearer SHARED_SECRET or x-task-callback-secret: SHARED_SECRET. It accepts no status description or data and only completes a task. Success is HTTP 204 with no body. A blocked task returns 409, invalid authentication returns 401, and missing server secret configuration returns 500. Organisation context is required; do not assume this endpoint is available on every deployment.
Use the execution-scoped status callback for new integrations. It resolves the organisation from the authenticated execution and supports progress and final data.