API Keys: Simple Server-to-Server Authentication
An API key is a simple secret token a client sends to prove its identity, often in a request header. It's ideal for machine-to-machine communication where a user login flow is unnecessary. Footgun: Never send keys in URL query parameters.
Why it exists
API key authentication exists to provide a simple, non-interactive way for a machine or service to authenticate itself to an API. Unlike complex flows like OAuth2 which often involve user consent and browser redirects, API keys are straightforward tokens designed for trusted, programmatic clients.
The mental model
Think of an API key as a key to a building's utility closet, not a key to a specific person's office. The key itself grants access; it doesn't matter who holds it. Any program with the key can open the door. This is different from a user's password, which is tied to their personal identity and permissions.
How it works
A client includes its secret API key with each request it makes. The most secure and common method is to place it in a custom HTTP header, like X-API-Key: your-secret-string. Your FastAPI application then uses a security dependency, like APIKeyHeader, to extract this value. The app checks if the provided key is valid, typically by looking it up in a database or a secure configuration file. If the key is valid and active, the request is processed; otherwise, it's rejected with a 401 or 403 error.
When to use it
Use API keys for server-to-server communication, internal microservices that need to talk to each other, or for granting third-party developers access to public, non-user-specific data (e.g., a public weather API). It excels when the client is a trusted, non-interactive program.
When not to use it
Do not use API keys to directly authenticate end-users in a web or mobile app. For that, use a protocol like OAuth2 that ties access to a specific user's identity and session. Also, avoid API keys if you need granular, per-user permissions, as a basic API key often grants the same level of access to any client that possesses it.
One canonical example
A third-party monitoring service needs to pull health check data from your API. You generate a unique API key for this service and share it securely. The service configures its requests to your /health endpoint to include the header Authorization: ApiKey <the-key>. Your FastAPI app uses the APIKeyHeader dependency on that endpoint to ensure only requests with that valid key can access it. All other requests are rejected.
Interview question
Which scenario is the most appropriate use case for API key authentication?
- a.Securing an interactive web form where users submit personal data to your server.
- b.Managing distinct permissions for different user roles accessing an internal dashboard.
- c.Allowing a third-party monitoring service to access your API's health endpoint.Correct
- d.Authenticating individual users when they log into a new mobile application.
Why? this is the answer
API keys are ideal for server-to-server communication or trusted, non-interactive clients, as exemplified by a monitoring service. They are not suitable for authenticating end-users or managing granular, per-user permissions, which are better handled by protocols like OAuth2.
Just read this? Test yourself on what you have been reading.
Read the original → fastapi.tiangolo.com
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on api — each one lists the topics its interview covers.
See open roles