API Keys and Service Accounts

For anything you automate against Rivolq, such as a nightly script or a custom integration, use a service account rather than a real user's credentials.

Service accounts vs user accounts

A service account is a non-human identity for programmatic access. It has no email or password and authenticates via API key. It does not count as a billed technician. It has a role, just like a user, and audit log entries are attributed to the service account rather than a person. Never put a real user's API key into a script: when that user is deactivated, the script breaks.

Creating and using one

Open Settings, then Service accounts, then New service account.

1. 01Name it specifically, for example Nightly export to BigQuery.
2. 02Choose a least-privilege role. An account that only reads work orders should be Viewer, not Admin.
3. 03Optionally restrict scope to specific facilities or asset categories.
4. 04Generate an API key and copy it now. You will not see it again. Store it in your secrets manager.

Pass the key as a bearer token in the Authorization header. The API base URL is https://app.rivolq.com/api/v1 (or your dedicated subdomain on Enterprise), following standard REST conventions. Full docs live under Settings, then Developer portal, then API reference.

Rate limits

Developer API traffic is currently limited to 600 requests per minute per session. Enterprise or contracted integrations may have additional controls documented in the agreement. A 429 Too Many Requests response can include retry headers. Back off and retry rather than hammering the API.

Rotation

Rotate quarterly for admin-scope keys, annually for read-only keys, and immediately if a key may have leaked. Open Settings, then Service accounts, then the account, then Rotate key. The old key keeps working for 7 days. Update your secrets manager, confirm the old key has gone silent in the audit log, then click Revoke old key.

OAuth and SDKs

If you are building an app that other Rivolq orgs will install, use OAuth instead of API keys. Register it under Developer portal, then OAuth apps; each customer authorizes it with scoped permissions. Service accounts are for your org; OAuth is for apps that operate across orgs.

Official SDKs exist for Python (pip install rivolq), Node.js (npm install @rivolq/sdk), and Go (go get github.com/rivolq/rivolq-go). They handle auth, retries, pagination, and rate-limit backoff. Do not store keys in source control or grant Admin just in case.