add advanced guide for apikey*

docs/en/docs/advanced/security/api-key.md

@@ -0,0 +1,66 @@
+# API Key Authentication
+
+Another authentication method, particularly for machine-to-machine communication, is an API key. An API key is a string that the application will expect with each request from a particular client. The API key can be sent as a header, a cookie, or a query parameter.
+
+If the API key is missing or invalid, the application returns an HTTP 401 "Unauthorized" error to the client.
+
+/// warning
+
+It is generally recommended to use API keys for programmatic access only, and to keep the API Key secret between the client(s) authenticated by the key and the server. Depending on your use case, this may mean storing this value in an environment variable or encrypted database (instead of hard-coding it, as in the examples below), and even providing a
+unique API key for each client trying to authenticate.
+
+///
+
+## Simple API Key Auth using Header
+
+* Import `APIKeyHeader`.
+* Create an `APIKeyHeader`, specifying what header to parse as the API key.
+* Create a `verify_api_key` function that checks the API Key in the Header.
+* Add `Depends(verify_api_key)` either globally or to a single endpoint (see example)
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial008.py!}
+```
+
+The client will need to send a request with the correct header:
+
+```http
+GET /secure-data HTTP/1.1
+X-API-Key: mysecretapikey
+```
+
+## API Key Auth using Cookies
+
+The process is similar to using `APIKeyHeader`, except we use a `APIKeyCookie`
+instance, instead:
+
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial009.py!}
+```
+
+The client will then need to pass in the key as a cookie (note that the name of the cookie is case-sensitive!):
+
+```http
+GET /secure-data HTTP/1.1
+Cookie: X-API-KEY=mysecretapikey
+```
+
+https://fastapi.tiangolo.com/reference/security/?h=apikeyheader#api-key-security-schemes
+
+## API Key Auth using Query Param
+
+/// warning
+Passing API keys via query params is considered less secure, since it will be
+visible as part of the URL (for example, in browser history or access logs).
+///
+
+Again, similar to the approaches above, except we use `APIKeyQuery`:
+```Python hl_lines="5  7  14  23"
+{!../../docs_src/security/tutorial010.py!}
+```
+
+The client will then need to pass in the key as part of the query param:
+
+```http
+GET /secure-data?api_key=mysecretapikey HTTP/1.1
+```

docs/en/mkdocs.yml

@@ -171,6 +171,7 @@ nav:
       - advanced/security/index.md
       - advanced/security/oauth2-scopes.md
       - advanced/security/http-basic-auth.md
+      - advanced/security/api-key.md
     - advanced/using-request-directly.md
     - advanced/dataclasses.md
     - advanced/middleware.md

docs_src/security/tutorial008.py

@@ -0,0 +1,21 @@
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.security.api_key import APIKeyHeader
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+API_KEY_NAME = "X-API-Key"
+api_key_header = APIKeyHeader(name=API_KEY_NAME)
+
+def verify_api_key(api_key: str = Depends(api_key_header)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}

docs_src/security/tutorial009.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.security.api_key import APIKeyCookie
+
+app = FastAPI()
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+api_key_cookie = APIKeyCookie(name="X-API-KEY") # case-sensitive!
+
+
+def verify_api_key(api_key: str = Depends(api_key_cookie)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}

docs_src/security/tutorial010.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.security.api_key import APIKeyQuery
+
+app = FastAPI()
+
+# Replace with your actual API key, ideally injected as an Environment Variable
+# or stored in a secure DB.
+API_KEY = "mysecretapikey"
+
+api_key_query = APIKeyQuery(name="api_key") # Note you have to use underscores
+
+
+def verify_api_key(api_key: str = Depends(api_key_query)):
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key")
+
+# Apply it for all endpoints
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+# Apply it for specific endpoints
+@app.get("/secure-data")
+def secure_endpoint(api_key: str = Depends(verify_api_key)):
+    return {"message": "You have access to secure data"}