Why SaaS applications need first-class API keys
Customer automations, scheduled jobs, command-line tools, and server-to-server integrations need identities that are independent from browser sessions. Copying a user's session into a script gives the workload the user's full interactive authority, obscures which integration made a request, and breaks when that session expires or is revoked. A first-class API key gives the workload its own owner, scopes, history, expiry, and revocation path.
A credential is a managed product object
The key record should contain a stable ID, visible prefix, owner, optional organisation, descriptive name, scopes, status, creation time, optional expiry, and last-used time. The raw value appears once at creation. Subsequent reads return metadata that lets a customer recognize the credential without turning the management API into a secret-retrieval endpoint.
Separate credentials for production, staging, local development, and each external integration make operations attributable. A leaked development key can be revoked without interrupting production. A migration key can expire on a fixed date. A support engineer can match a safe prefix in an audit event to the named integration without ever seeing the complete bearer credential.
Ownership defines the lifecycle
A user-owned key is appropriate for personal automation and derives its identity from that account. auth.verifyApiKey rejects the key when its owning user is missing or disabled. Organisation membership is separate: removing a membership does not revoke a user-owned key, so every tenant request must verify current membership as well as the key. Revoke the key when its intended integration ends.
An organisation-owned key represents shared infrastructure such as a deployment system or production data pipeline. It survives an individual staff change, while creation, inspection, and revocation remain restricted to authorised members. Own Auth requires the built-in manage_api_keys permission for organisation key management. Assigning ownership at issuance avoids deciding during offboarding whether an integration was personal or operational.
Scopes turn identity into bounded authority
A verified key identifies the integration. Scopes constrain which product operations it may request. Define scopes around stable capabilities such as invoices:read, reports:write, or webhooks:manage, then require them at the backend operation that uses them. Interface labels and pricing plans make poor scope names because they change independently from authorization behavior.
Scope checks do not replace tenant and object authorization. A key owned by one organisation must not read another organisation's invoice because the request contains a different tenant ID. Resolve the owner returned by verification, constrain the application query to that owner, and then enforce resource-specific policy. Wildcard access should be an explicit exception for controlled workloads rather than the default choice in a creation form.
Own Auth's API key model
auth.createApiKey creates user-owned and organisation-owned keys, returns the raw key once, stores a peppered hash, and writes a supported audit event. auth.listApiKeys returns safe metadata. auth.verifyApiKey rejects invalid, expired, or revoked keys and can require specific scopes. Own Auth updates last-used metadata on successful verification. The application supplies the meaning of each scope and performs authorization for its own records.
Use Authorization: Bearer over HTTPS for incoming application keys. Do not accept keys in URLs, browser bundles, or mobile binaries. URLs leak into histories, referrers, proxy logs, and monitoring systems, while public client code cannot keep a shared secret. Reject invalid credentials with one narrow response and omit the supplied value from logs, traces, and exception metadata.
Rotation without a shared outage
Rotation should create a replacement record, move the integration to it, confirm traffic on the new prefix, and revoke the original. A short overlap allows deployment without losing attribution. Updating one shared secret in place creates an ambiguous cutover and makes rollback harder because old and new traffic refer to the same record.
Revocation should affect the next verification and preserve the record's audit history. Expiry is useful for temporary workloads, but it is not a response to confirmed exposure because the credential remains usable until the deadline. Rate limits can also be applied per key so one integration cannot consume the allowance of every other customer workload.
Where API keys stop
An API key is appropriate when one server-side workload calls another service under a fixed owner. It is not a complete delegated authorization protocol. A third-party application acting for many users may require OAuth consent and delegated grants. A high-value internal service may combine a key with network policy, signed requests, or mutual TLS. OWASP advises against relying exclusively on API keys for sensitive or critical resources.