API keys let you integrate Userorbit with your own systems, automate workflows, and build custom integrations. This guide covers where to find your API keys, how to create new ones, understanding key permissions, and revoking keys you no longer need.
Where to find your API keys
- Log in to your Userorbit workspace.
- Go to Settings in the left sidebar.
- Click API Keys.
This page lists all API keys associated with your workspace, along with their name, creation date, last used date, and permission level.
Create a new API key
- On the API Keys page, click Create API Key.
- Enter a name for the key. Use a descriptive name that indicates its purpose — for example, "CI/CD Pipeline," "Analytics Integration," or "Zapier Connection."
- Select the permission level for the key (see permissions below).
- Click Create.
Your new API key will be displayed once. Copy it immediately and store it securely. Userorbit does not display the full key again after this step. If you lose it, you will need to create a new one.
Key permissions
API keys can have different permission levels to follow the principle of least privilege:
- Read-only — Can fetch data from Userorbit (articles, announcements, feedback, contacts) but cannot create, update, or delete anything. Use this for analytics dashboards or reporting tools.
- Read and write — Can both read data and create or update resources. Use this for integrations that need to push data into Userorbit, such as creating announcements from a CI/CD pipeline or syncing contacts.
- Full access — Can perform all operations, including deleting resources and managing settings. Use this sparingly and only for trusted internal tools.
Always choose the most restrictive permission level that still allows your integration to function. You can create multiple keys with different permissions for different integrations.
Using your API key
Include your API key in the Authorization header of every API request:
Authorization: Bearer YOUR_API_KEY
You also need to include your team ID in the x-team-id header:
x-team-id: YOUR_TEAM_ID
The Userorbit API base URL is https://api.userorbit.com/api/v1. All endpoints use the POST method. Refer to the API documentation for the full list of available endpoints.
Rotate a key
If you suspect a key has been compromised, or as part of regular security hygiene, rotate it:
- Create a new API key with the same permissions and a similar name.
- Update your integration to use the new key.
- Verify the integration works with the new key.
- Revoke the old key (see below).
This approach avoids downtime — your integration keeps working with the old key until you have confirmed the new one is in place.
Revoke a key
To deactivate a key you no longer need:
- Go to Settings > API Keys.
- Find the key in the list.
- Click the menu icon and select Revoke.
- Confirm the revocation.
Revoked keys stop working immediately. Any integration using that key will receive authentication errors. This cannot be undone — if you need the integration to work again, create a new key.
Security best practices
- Never commit API keys to version control. Use environment variables or a secrets manager.
- Use separate keys for separate integrations so you can revoke one without affecting others.
- Regularly audit your keys on the API Keys page. Revoke any that are no longer in use.
- Use the "last used" date to identify stale keys that may no longer be needed.