Overview
Organization API keys let external tools and scripts call the Corvid API on behalf of your organization — without impersonating a user. Every key is scoped to the organization that issued it, so a key created in Organization A can never read or write data in Organization B.
Typical use cases include:
Syncing a hotlist from an internal system.
Gate-guard tooling that queries plates against the organization's watchlists.
Scheduled reports or exports run by a back-office script.
Who can create API keys: only organization owners and superusers can view or manage API keys. Other members will not see the API Keys tab inside Manage Organization.
How to manage API keys
All key management happens inside Manage Organization → API Keys. This section covers creating, viewing, and revoking keys.
Create an API key
Open Manage Organization
In the top-left of the sidebar, click the organization switcher (your organization name and logo).
From the dropdown, select Manage Organization.
The dialog opens with a left-hand navigation:
General
Members & Invitations (with sub-tabs Members and Invitations)
API Keys
Contact Information
Settings
Click API Keys. You will see a list of any keys that already exist, with columns for Name, Last used, and Actions. Use the search bar at the top-right to filter by name.
Fill in the create form
In the top-right of the API Keys panel, click the + icon.
The Create API Key dialog opens.
Enter a Name — for example, "Gate-A guard tablet" or "Nightly hotlist sync". The name only identifies the key on the list; it does not affect what the key can do.
Optionally add a Description explaining the key's purpose (which system or team will use it).
Optionally set an Expiration Date. If you leave this blank, the API key will never expire. For third-party or short-lived integrations, always set an expiration.
Click Create API Key.
Copy and store the secret
After you click Create, a confirmation dialog appears with the generated key (secrets start with the ak_ prefix):
Copy your API key now. You will not be able to see it again.
Click the copy icon next to the key value.
Paste it into a secrets manager or secure vault immediately.
Click Close when done.
If you lose the key, you cannot recover it — you will have to create a new one and revoke the old.
Tip: issue one key per external integration or per device fleet. Separate keys make it easier to identify who is calling the API and to revoke a single caller without disrupting the others.
View existing keys
Back in the API Keys tab you can see, for each key:
Name and the created / expiration dates.
Last used — the date the key most recently authenticated a request, or Never if it hasn't been used yet.
Actions — a menu (⋮) for revoking or editing the key.
Revoke or rotate a key
Open Manage Organization → API Keys.
Find the key you want to remove and open the Actions menu (⋮).
Choose Revoke (or the delete action) and confirm.
The key stops working immediately — any request made with it will return 401 Unauthorized.
To rotate a key with minimal downtime:
Create a new key with a matching name (for example, add a "-v2" suffix).
Update the external integration to use the new key.
Confirm the new key is being used (check Last used in the list), then revoke the old one.
How to use an API key
Send the key on every API call in the Authorization header using the ApiKey scheme (note: ApiKey, not Bearer):
Authorization: ApiKey ak_XXXXXXXXXXXXXXXXXXXX Content-Type: application/json
Example — list the organization's private hotlists:
curl "https://<api-base-url>/v2/hotlists" \ -H "Authorization: ApiKey $CORVID_API_KEY"
The api-base-url depends on the environment (Production, Staging, or Development). See What environments does we support? for the matching hosts.
Requests made with an API key are attributed in the audit log to the identity API Key rather than to a specific user, so use descriptive key names to keep the trail readable.
Security best practices
Never commit keys to source control. Store them in a secrets manager (AWS Secrets Manager, 1Password, Doppler, etc.) and inject them at runtime.
Do not share keys between integrations. Issue one per integration so you can revoke a single caller if it is compromised.
Set an expiration when you can. Time-boxed keys reduce the blast radius of a leak.
Rotate periodically. Even without a known incident, rotating on a schedule reduces exposure.
Restrict access. Only grant the organization owner role to people who truly need to manage keys.
Troubleshooting
401 Unauthorized — the key is missing, malformed, expired, or has been revoked. Verify the Authorization header uses the ApiKey scheme (not Bearer) and that the key value starts with ak_.
403 Forbidden — the key is valid but the caller does not have permission for the resource. Confirm the key belongs to the correct organization.
I don't see the API Keys tab. Your account is not an organization owner or superuser. Ask an existing owner to grant you the role or to create the key on your behalf.
Related articles
How to manage your organization settings in Corvid
What is the Permissions System?
What environments does we support?