API Keys

API access keys authenticate integrations with Authorization: Bearer <key>. They are long-lived JWT credentials bound to the issuing organisation and user, with an expiry set by the Ovee server.

Create a key

1. Sign in to the correct Ovee environment as an administrator of the organisation you want to integrate.
2. Select that organisation and open Organisation Settings → APIs.
3. Enter a descriptive name, such as Payroll integration, and select Create API Key.
4. Copy the full token immediately and store it in your integration’s secret store. The app only shows the full token when it is created.

Open API settings in Ovee →

Keep credentials on your server

Do not put a key in browser code, source control, a URL, or a webhook payload. This documentation site does not ask you to enter your key.

Authenticate requests

Set OVEE_BASE_URL to the application origin that issued your key and supply OVEE_API_KEY through your local environment or secret manager.

curl --fail-with-body \
  --header "Authorization: Bearer $OVEE_API_KEY" \
  "$OVEE_BASE_URL/api/webhooks/capabilities"

This returns whether webhook delivery is enabled and signing is configured. Webhook management requires organisation administrator access. Resource GET operations retain their existing user and organisation permissions.

Replace or revoke a key

Create a replacement key, update your integration’s secret store, and confirm a read-only request succeeds. Then revoke the old key under Organisation Settings → APIs. Revocation invalidates subsequent authenticated requests using that key.

If you lose the full token, create a new key. The existing-key list only shows a masked suffix. Revoke a lost or exposed key promptly.

Webhook signing secrets are separate credentials. Replacing an API key does not rotate a subscription’s signing secret or transfer ownership: subscriptions belong to the organisation.

Troubleshooting

Symptom	What to check
401 Unauthorized	Correct environment, complete Bearer header, and a key that has not expired or been revoked.
403 Forbidden	Issuing user’s current roles, organisation access, and the permissions required by the operation.
404 Not Found	Correct identifier and organisation. Some operations deliberately return 404 for resources in another organisation.
412 Precondition Failed	Operation-specific prerequisites or organisation context; inspect the response for details.
Webhooks unavailable	Ask your Ovee administrator to check delivery and signing configuration. Key management can still work while webhooks are unavailable.

Use a separate named key for each integration so that it can be replaced or revoked independently.