Security guide · v1.0.0
Authenticate every request with an organization key.
API keys are machine credentials managed by organization admins in crewQI. They are scoped, environment-bound, and never log a person into the crewQI app.
Bearer token
Send the complete key in the HTTP Authorization header. Do not put it in a URL, browser session, client-side bundle, or log.
Authorization: Bearer cqi_live_<key-id>.<secret>The full secret is returned only when a key is created or rotated and is hashed at rest. If it is exposed, revoke it immediately and create a replacement.
Scopes
Choose narrow resource scopes when creating a key. There is no wildcard scope. Sensitive employee fields require employees:read_sensitive in addition to employees:read.
Bank accounts are a separate individual subresource. Reading requires both employees:read and employees:read_financial; setting or clearing requires both employees:write and employees:write_financial. Existing keys do not gain financial access automatically.
Financial scopes depend on their matching base scope. The admin app selects the dependency and the database rejects invalid combinations. See the bank-account integration guide.
Time permissions are separated: work_events:read reads safe immutable evidence, timesheets:read reads canonical effective time, timesheets:write performs audited corrections, and audit:read reads the safe organization trail. There is no raw-event write scope.
timesheets:write can be granted only while the organization correction entitlement and rollout proof are enabled. Disabled writes return FEATURE_NOT_ENABLED. See time entries and corrections.
TEST and LIVE
TEST and LIVE are paired environments with distinct organization IDs. TEST contains synthetic fixtures and customer-created integration data; it does not copy production data or credentials.
| Environment | Key prefix | API host | Organization boundary |
|---|---|---|---|
| TEST | cqi_test_ | api-test.crewqi.com | TEST organization ID only |
| LIVE | cqi_live_ | api.crewqi.com | LIVE organization ID only |
Changing the host, URL, or resource ID cannot cross the boundary. A key’s environment is part of the organization identity, not a mode that can be switched on one key.
Validity, rotation, and revocation
Keys can be valid for 7, 30, 90, 180, or 365 days, a custom expiration, or unlimited validity. Unlimited validity is an explicit choice, not an omitted policy. Expiration is enforced using the key’s absolute expiresAt.
- Rotate before a planned change. Rotation creates a replacement while the old key remains active.
- Deploy the replacement. Verify the integration against the intended environment.
- Revoke the old key. Revocation and expiration take effect at request authentication.
The default limit is 600 requests per minute per key. A 429 response includes Retry-After and an RFC 9457 problem with code RATE_LIMITED; use bounded exponential backoff.