Secure your API access
API keys allow external applications and scripts to interact with your Userorbit workspace programmatically. Managing them properly is essential to keeping your workspace secure. This guide covers the full lifecycle of API key management.
Generating a new API key
- Navigate to Settings → API Keys in the dashboard. You need Admin permissions to access this page.
- Click Create API Key.
- Enter a name for the key. Use a descriptive name that identifies its purpose (e.g., "CI/CD Pipeline", "Zapier Integration", "Internal Dashboard").
- Select the permissions scope for the key. Choose the minimum permissions needed for the key intended use.
- Click Generate.
- The key is displayed once. Copy it immediately and store it in a secure location such as a password manager or secrets vault. You will not be able to see the full key again.
Key scopes and permissions
API keys can be scoped to limit their access:
- Read-only — the key can fetch data (feedback, announcements, users) but cannot create, update, or delete anything. Use this for dashboards and reporting tools.
- Read and write — the key can both read and modify data. Use this for integrations that need to create feedback or update statuses.
- Full access — the key has access to all API endpoints including workspace settings. Reserve this for trusted internal tools only.
Always choose the narrowest scope that satisfies the use case. A reporting dashboard does not need write access. A webhook handler that only creates feedback does not need full access.
Rotating keys
Key rotation is the practice of replacing an active key with a new one on a regular schedule. To rotate a key:
- Generate a new key with the same scope as the one you are replacing.
- Update the application or integration to use the new key.
- Verify the application works correctly with the new key.
- Revoke the old key.
Rotating keys regularly (e.g., every 90 days) limits the window of exposure if a key is compromised without your knowledge.
Revoking compromised keys
If you suspect a key has been exposed or compromised, revoke it immediately:
- Go to Settings → API Keys.
- Find the key in the list.
- Click the three-dot menu and select Revoke.
- Confirm the revocation.
The key stops working immediately. Any application using it will begin receiving authentication errors. Generate a new key and update the affected application as soon as possible.
Monitoring key usage
The API Keys page shows the last used timestamp for each key. Review this periodically:
- Keys that have not been used in a long time may be orphaned and should be revoked.
- Keys showing unexpected recent activity may indicate unauthorized use.
Best practices
- One key per integration — create a separate key for each application or integration. This way, revoking one does not break others.
- Never commit keys to source code — store API keys in environment variables or a secrets manager, never in git repositories or configuration files checked into version control.
- Use the narrowest scope possible — limit each key to only the permissions it needs.
- Rotate on schedule — set a reminder to rotate keys every 90 days.
- Revoke immediately when in doubt — if there is any chance a key has been exposed, revoke it first and investigate second.
- Audit regularly — review all active keys quarterly. Remove any that are no longer needed.