OAuth and API Key Management
OAuth credentials and API keys must be issued to organisation-owned accounts, restricted by environment and scope, stored outside source control, and rotated through a documented two-key transition where the provider allows it.
What You Will Be Able to Decide
- Explain the role of oauth and api key management in a self-hosted system.
- Apply the procedure to a real open-source deployment.
- Recognise unsafe defaults and verify the resulting control.
- Record enough evidence for another operator to repeat or recover the work.
Self-hosted applications often depend on external identity, email, storage, payment, or AI providers. Owning the server does not remove those trust relationships.
OAuth separates a user's authorisation from the application's identity. The client ID is usually public; the client secret authenticates the application and must remain confidential. The redirect URI is a security boundary because it decides where an authorisation response can return.
Credentials should identify an environment and a purpose. A development key, staging OAuth app, and production credential should not be interchangeable.
Technical term
OAuth redirect URI
The exact application URL to which an authorisation server returns the user after approval, usually carrying a short-lived code.
It is the verified return address on a secure delivery, not a general forwarding instruction.
The Working Model
Create provider applications under an organisation account, not a departing developer's identity. Register the exact HTTPS production callback from the self-hosted application's documentation and use separate provider applications for local, staging, and production environments.
Grant the smallest scopes required. Store secrets in the deployment platform's protected environment store or a dedicated secret manager, restrict who can reveal them, and make logs redact headers, tokens, and callback parameters.
Rotation should be rehearsed before an incident. Where a provider permits overlapping credentials, create the replacement, update and verify the application, then revoke the old credential. If overlap is impossible, schedule a maintenance window and prepare rollback.
Implementation Procedure
- List each provider, credential owner, environment, purpose, scope, creation date, and rotation procedure.
- Create separate OAuth clients and API keys for development, staging, and production.
- Register exact HTTPS callback URLs and avoid broad wildcard redirects.
- Inject credentials at runtime, confirm they do not appear in Git, images, logs, or client-side bundles.
- Test rotation and revocation, then record the evidence and next review date.
# Safe names in .env.example; never commit the real values
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URI=https://app.example.com/auth/callback
EXTERNAL_API_KEY=Controlled Practice and Fragile Practice
Verification and Recovery Evidence
- Authentication succeeds from the public production hostname and fails for an unregistered callback.
- Secret scanning finds no live credential in repository history or application bundles.
- A replacement credential can be deployed and the old credential revoked.
Warning Signs
- A production integration depends on one person's provider account.
- An API key appears in a client-side network request.
- No one knows what will stop working when a credential is revoked.
Questions to Ask a Consultant
- Who owns and can recover each provider account?
- Which scopes are necessary for the exact workflow?
- Can credentials rotate without a long outage or an unreviewed emergency change?
Key takeaway
Key Takeaway
Treat OAuth and API credentials as governed production dependencies: exact callbacks, least privilege, durable ownership, confidential storage, and rehearsed rotation.