# API Key

A secret or identifier presented by a software client to associate API requests with a project, application, or principal.

- Type: artifact
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/api-key/>)

## What it means

An API key is a value issued to a client and sent with API requests. Depending on the system it may identify usage, authenticate a workload, authorize limited access, or only support metering. A static bearer key proves possession, not the identity of the person operating the client.

## Why it matters

API keys provide simple machine access and attribution, but leaked keys are easy to replay. Issuance, scope, storage, rotation, monitoring, and revocation determine whether convenience becomes persistent unauthorized access.

## When to use it

Use API keys for controlled machine clients and low-complexity service access when their limitations are acceptable. Use OAuth, workload identity, mutual TLS, or signed requests when delegation, short lifetimes, stronger client proof, or user context is required.

## How it works

1. Issue a high-entropy key to a named owner and show the secret through a protected channel.
2. Store only a protected form where possible and keep the client copy in a secret manager.
3. Send it in an approved header over TLS, never in a public client or URL.
4. Look up the key, enforce scope and limits, and record safe usage metadata.
5. Rotate keys with overlap and revoke them on expiry, disuse, or suspected exposure.

## A practical example

A reporting service receives a read-only API key for one tenant. The key lives in its secret manager, requests are rate-limited and logged, and two active-key slots allow rotation without downtime.

## Where it breaks

Static keys are commonly bearer credentials with no user identity, phishing resistance, or built-in expiry. Keys embedded in mobile apps, browser code, repositories, logs, or URLs should be assumed recoverable.

## Common mistakes

- Embedding a secret API key in downloadable frontend or mobile code.
- Sending keys in query strings that enter logs and histories.
- Issuing one permanent key shared by many systems.
- Treating identification by a public or restricted key as strong authentication.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/api-key/#visualization-api-key>)

## Sources

1. [REST Security Cheat Sheet](<https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html>) — OWASP Foundation · Security practice guidance
2. [API Keys API Documentation](<https://cloud.google.com/api-keys/docs/overview>) — Google Cloud · Official technical documentation

## Related topics

- [Authentication](<https://wiki.soroush.uk/topic/authentication/>)
- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
- [Secrets Management](<https://wiki.soroush.uk/topic/secrets-management/>)
