Skip to main content
A user API key lets you call the incident.io API as yourself. The key has exactly the permissions your account has, so a script you run with it can do what you can do in the dashboard, and nothing more. When you’re deactivated, your user keys are deleted with you, so there are no leftover keys to clean up. User keys suit personal scripts, CLI tools, and local automation. For shared integrations that should keep working regardless of who set them up, use an organization API key instead. User API keys are available on plans that include API access.

​
Creating a user API key

We’ll only show the token once at creation time, so store it somewhere safe.
  1. Go to Settings → Authentication methods and open the User keys tab
  2. Click Create user API key
  3. Give the key a name that tells you where it’s used (e.g., “Local scripts”)
Use the token in the Authorization header, the same way as an organization key. See Authentication for an example request.

​
Permissions

A user key doesn’t have its own set of permissions. Every request checks your current role, so if your role changes, the key’s access changes with it straight away. User keys work with the public API. They can’t create, edit, rotate, or delete organization API keys, so a key you create can never outlive your own access.

​
Who can create user keys

Creating a user key requires the Create user API keys permission. The User, Admin, and Owner base roles include it by default. To stop people with a particular role from creating keys, remove the permission from that role in Settings → Permissions → Account-level. See User permissions for how roles work.

​
When someone leaves

When a user is deactivated, their user API keys stop working immediately and are deleted. You don’t need to find and revoke them by hand.

​
Managing keys across your organization

Admins can see and delete every user API key in the organization from Settings → API keys, on the User keys tab. You can search by key name or by the person who owns it, and select several keys to delete them together. This requires the Manage all users’ API keys permission, which the Admin and Owner base roles include by default.

​
Seeing what a key did

Actions taken with a user key are recorded as the person who owns it. In the dashboard, they show the person’s name followed by a key icon, so you can tell a scripted change apart from one made by hand. Creating and deleting user keys is recorded in your audit logs.

​
Rate limits

All of a person’s user keys share one rate limit of 1,200 requests/minute. Creating incidents is limited in the same way as for organization keys, counted per person across their user keys. See Rate limits for the details.

​
FAQs

Use a user key for work you do yourself, like personal scripts and local tools. Use an organization key for integrations your team depends on, since organization keys keep working when the person who created them leaves.
No. A user key works until you delete it, an admin deletes it, or your account is deactivated.
We work with GitHub secret scanning. If a user key is pushed to a public GitHub repository, we delete it automatically and email you and your organization’s admins. Create a new key to replace it.
No. A user key always has the same permissions as your account. If you need a key with a narrower set of permissions, create an organization key and choose exactly the permissions it needs.