How to create API keys
An API key lets an external system act on your organization's data through UniAsset's REST API.
Requirements
- Available on: Odyssey, Cosmos
- Roles: Owner only
Steps
- Go to Settings → Integrations → API Keys.
- Click New API Key.
- Configure it:
| Setting | Notes |
|---|---|
| Name | A human-readable label — name it after the system that will use it |
| Permissions | One or more scopes. At least one is required. |
| IP allowlist | Optional. Restricts the key to specific addresses. |
| Rate limit | Requests per minute, 1–1000. Defaults to 60. |
- Create.
Warning The key is shown once. UniAsset stores only a short lookup prefix and a hash of it, so it cannot be retrieved afterwards. Copy it into your secret manager before closing the dialog. If you lose it, revoke the key and create a new one.
Permission scopes
Grant the minimum a system needs.
| Scope | Grants |
|---|---|
asset:create | Create assets |
asset:update | Update assets |
asset:location | Update geo position |
assignment:update | Change asset assignment |
maintenance:create | Create service records |
iot:signal:ingest | Ingest IoT signals |
A telemetry pipeline needs iot:signal:ingest and nothing else. A key that can do everything is a key whose compromise costs you everything.
One key per integration
Give each connected system its own key.
Then when one system is decommissioned, or its key leaks, you revoke exactly that key. A single shared key means revoking it breaks every integration at once, and the activity log cannot tell you which system did what.
Using a key
Send it as a bearer token in the Authorization header. The key format is ua_live_ followed by 64 characters.
Full endpoint reference: Getting started with the REST API.
Revoking a key
Revocation is immediate. A revoked key fails authentication on the next request.
Revoke when:
- A system is decommissioned
- A key may have been exposed
- Someone with access to it leaves
Rate limits and payload size
- Rate limit is per key, 1–1000 requests per minute, default 60.
- Payload size is capped at 1 MB, checked before anything is parsed.
What happens if you downgrade
Keys are not revoked by a plan change. They stop authenticating while the capability is absent and work again on upgrade, with nothing to reconfigure.
Common mistakes
Not storing the key at creation. It cannot be retrieved. This is the most common support request on this feature.
Granting every scope "to be safe". That is the opposite of safe.
Putting the key in client-side code or a public repository. Anything reaching a browser is public.
Sharing one key across every integration. You lose the ability to revoke or attribute precisely.
Troubleshooting
I can't find API Keys. It needs Odyssey or above, and Owner.
401 KEY_NOT_FOUND or 401 INVALID_KEY. The key is wrong, truncated, or from a different organization. Check it was copied whole.
401 KEY_REVOKED. The key was revoked. Create a new one.
403 PLAN_UPGRADE_REQUIRED. Your plan does not include API access. Odyssey or above is required.
403 FORBIDDEN. The key authenticated but lacks the scope for that endpoint. Check its permissions.
413 PAYLOAD_TOO_LARGE. The body exceeds 1 MB.
Requests work from one machine but not another. Check the key's IP allowlist.
I lost the key. Revoke it and create a new one. There is no recovery path, by design.
Related articles
Need Help?
If you have questions not covered in this article, our support team is here to help.
Contact Support