API Keys, Sessions, and Service Credentials Explained

Introduction

A reporting integration might send a project API key with each request:

GET /v1/reports HTTP/1.1
X-API-Key: key_example_123

That key can identify the integration or enforce a quota, but it does not decide which report the caller may access. A browser session represents a signed-in user, while a service credential represents a workload. Validate the credential, then authorize the requested action and resource. OAuth and OpenID Connect explains user and delegated identity flows.

Choose credentials for the client

• Browser application: Use a session cookie or a suitable short-lived identity token. For cookies, set HttpOnly, Secure, and an appropriate SameSite policy; protect state-changing requests against CSRF.
• Service workload: Prefer workload identity or short-lived service tokens when the platform supports them. Give each workload its own identity and narrowly scoped permissions.
• Partner or project integration: An API key can identify the integration and support quotas. Scope it, store it as a secret, and avoid treating it as a human user’s identity or authorization policy.

Credential validation and authorization flow

flowchart TD
  A[Client presents credential] --> B[Validate credential, expiry, and status]
  B --> C[Resolve caller identity and scope]
  C --> D[Authorize requested action and resource]
  D -->|Allowed| E[Process request]
  D -->|Denied| F[Return safe error]
  E --> G[Record outcome without secrets]

Implementation practice

Validate credentials at the API boundary before handlers use the caller identity. Check authorization separately for the requested action and object; never trust identity or permission claims supplied in ordinary request data. Keep secrets out of examples and logs, and add tests for expired, revoked, and insufficiently scoped credentials as well as the allowed path.

Rotating credentials without service interruption

For a planned rotation, issue a replacement credential while the current one is still valid, then give the caller a clear migration window. Track credentials by a non-secret identifier so telemetry can show which key is still in use without logging its value. Once callers have moved, revoke the old credential and confirm that rejected uses are understood.

Keep the overlap bounded and assign an owner and deadline. If the replacement fails, make rollback explicit: pause revocation, restore the previous credential only if it remains safe, and resolve the cause before extending the overlap. Suspected compromise is different from routine rotation; revoke or disable the exposed credential promptly and use the incident process rather than waiting for ordinary migration.

Production failure scenarios and mitigations

• A rotated or expired credential causes a caller outage. Monitor rejection rates by non-secret credential ID and use a bounded overlap for planned rotation.
• Several workloads share one API key. Issue separate credentials so a leak can be traced and contained without disabling unrelated callers.
• A secret appears in logs or an error report. Redact values at ingress and in application telemetry, restrict log access, and rotate the exposed credential through the incident process.
• A revoked session remains usable. Invalidate the session server-side at logout or privilege changes, and test that stale session identifiers are rejected.

Trade-off Analysis

Observability checklist

• Track authentication success and rejection by credential type and non-secret identifier.
• Monitor expiration, revocation, rotation overlap, and unusual use from new clients or locations.
• Correlate failures with request IDs while redacting secret values from logs and traces.
• Alert on unexpected rejection spikes and review dashboards after credential changes.

Security and Compliance Notes

Use TLS and least privilege. Validate credentials at the server boundary, then authorize the requested action and resource; apply the same checks to alternate routes and batch operations. Keep credentials and sensitive payloads out of URLs, examples, analytics, and error messages. Record who or which workload issued, rotated, or revoked a credential, along with its scope and timestamp, but never store the secret value in audit records. Set access and retention rules for those records to match service policy. For browser sessions, rotate the session identifier after login or privilege changes and invalidate it at logout. Give each integration its own API key so a suspected leak can be traced and contained without disrupting unrelated callers.

Quick Recap Checklist

• Use user sessions for user-facing authentication and service credentials for workloads.
• Give each credential only the access its caller needs.
• Store secrets outside source code and redact them from logs.
• Set up rotation, revocation, and monitoring for unusual use.

Interview Questions

Further Reading

• OAuth 2.0, OpenID Connect, and Token Flows — user identity and delegated access.
• Authentication vs. Authorization — separate caller identity from permission checks.
• Scopes, Roles, and Object-Level Permissions — apply authorization at the resource level.
• Input Validation, Secrets, and Sensitive Data — handle sensitive values safely at API boundaries.
• OWASP Secrets Management Cheat Sheet — storage, access, rotation, and lifecycle guidance for secrets.
• OWASP Session Management Cheat Sheet — session identifiers, cookies, expiration, and invalidation.
• MDN: HTTP cookies — cookie attributes and browser behavior.

Conclusion

Use sessions for people, workload credentials for services, and scoped API keys for integrations that need them. Keep each credential attributable, monitor its use, and make rotation and revocation part of its lifecycle so one caller’s secret does not become everyone else’s risk.