API Keys

API keys give users and automated workflows a way to authenticate with Permiso's API without going through the passkey login flow. They're useful for scripts, CI/CD pipelines, and integrations that need to interact with Permiso programmatically.

Each API key is tied to a specific user account and inherits that account's permissions.

Creating an API key

Users can create their own API keys from Settings → Account → API Keys. Admins can also create and manage API keys for any user from Settings → Administration → API Keys.

To create a key:

1. Click New API Key
2. Give it a descriptive name (something that tells you what it's used for, like deploy-script or monitoring-integration)
3. Optionally set an expiry date. Keys without an expiry are valid indefinitely
4. Click Create

Copy the key immediately. It's only shown once. If you lose it, you'll need to create a new one.

Using an API key

Include the API key in the Authorization header of your requests:

X-API-Key: YOUR_API_KEY

Key expiry

If you set an expiry date, Permiso will send you an email notification before the key expires (if email notifications are enabled). You can also manually renew a key from the API keys list before it expires.

Expired keys stop working immediately when they expire.

Revoking a key

To revoke a key, click the Revoke button next to it in the list. Revoked keys stop working immediately. The key record is removed.

Admin-level API access

If you need a key with full admin access (for example, for a provisioning script that creates users), make sure you create it from an admin account. The key will have the same level of access as the user it belongs to.

There is also a static API key option configured via the STATIC_API_KEY environment variable, which can be useful for automated deployments. See Environment Variables for details.