Skip to main content

API Keys

API keys give you a secure way to authenticate administrative API requests and enable dynamic OAuth client registration from your applications. Unlike user access tokens, API keys are long-lived credentials scoped to your tenant.

What API Keys Are Used For​

PurposeDescription
Admin API accessAuthenticate calls to the tenant admin API (/t/{tenantSlug}/api/v1/admin/*)
Dynamic client registrationAllow your application to register OAuth clients programmatically (RFC 7591)
Server-to-server automationProvision users, manage roles, sync data from a backend service

Managing API Keys​

Go to /t/{tenantSlug}/portal/settings/api-keys to manage all API keys for your tenant.

Creating an API Key​

  1. Click Create API Key
  2. Enter a descriptive name (e.g., "CI/CD pipeline" or "Backend provisioning")
  3. Click Create
  4. Copy the key immediately — it is only shown once and cannot be retrieved again
Store your key securely

LumoAuth stores only a hashed version of the key. If you lose it, you must rotate it to get a new one.

Key Lifecycle​

ActionDescription
CreateGenerates a new key; shown in full only at creation
RotateGenerates a replacement key and immediately invalidates the old one
RevokePermanently disables the key
DeleteRemoves the key record from the portal

Using an API Key​

Include the key as a Bearer token in the Authorization header:

curl https://your-domain.com/t/{tenantSlug}/api/v1/admin/users \
  -H "Authorization: Bearer {your-api-key}"

Alternatively, some endpoints accept the key in an X-API-Key header:

curl https://your-domain.com/t/{tenantSlug}/api/v1/admin/users \
  -H "X-API-Key: {your-api-key}"

Rotating an API Key​

When you suspect a key has been compromised, or as part of regular key rotation practice:

  1. Go to /t/{tenantSlug}/portal/settings/api-keys
  2. Find the key and click Rotate
  3. Copy the new key — it is shown only once
  4. Update your applications to use the new key
  5. The old key is invalidated immediately upon rotation

Best Practices​

  • Use one key per service — name keys after the service that uses them so you can revoke individual services without affecting others
  • Rotate keys periodically — treat API keys like passwords and rotate them on a schedule
  • Never expose keys in client-side code — API keys have admin-level access; only use them in server-side code
  • Monitor key usage — suspicious API calls appear in Audit Logs