Authorization and integrity
Genkit HTTP handlers (serve_flow, genkit_fastapi_handler,
genkit_flask_handler, and genkit_django_handler) perform no authentication
by default. Any caller who can reach the route can invoke the action.
Securing a deployed Python flow has three parts:
- Authenticate at the HTTP boundary and attach verified caller identity to
the action
contextdict before the flow runs. - Authorize inside the flow and tools by reading identity from
FlowContext/ToolContext, never from model-generated tool arguments or raw prompt input. - Return safe HTTP errors using
PublicError, since plain exceptions and internalGenkitErrorinstances are redacted to generic500responses on the wire.
Authenticate at the handler
Section titled “Authenticate at the handler”FastAPI (genkit-fastapi)
Section titled “FastAPI (genkit-fastapi)”serve_flow accepts a context_dependency, so you can reuse FastAPI Depends
auth. Its return value becomes the flow’s context. FastAPI runs it before
Genkit’s handler, so reject with HTTPException; a PublicError raised there
becomes a 500.
import hmacimport osfrom typing import Any
from fastapi import Depends, FastAPI, HTTPException, statusfrom fastapi.security import HTTPAuthorizationCredentials, HTTPBearerfrom genkit import FlowContext, Genkit, PublicErrorfrom genkit_fastapi import serve_flowfrom genkit_google_genai import GoogleAI
# 1. Initialize Genkitai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))bearer_scheme = HTTPBearer(auto_error=False)
# 2. Verify the caller in a FastAPI dependencyasync def require_caller( creds: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),) -> dict[str, Any]: expected_token = os.environ['INTERNAL_API_TOKEN'] if creds is None or not hmac.compare_digest(creds.credentials, expected_token): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail='Valid bearer token required.', headers={'WWW-Authenticate': 'Bearer'}, ) return {'auth': {'uid': 'support-bot', 'role': 'support'}}
# 3. Read the verified identity inside the flow@ai.flow()async def summarize_ticket(ticket_text: str, ctx: FlowContext) -> str: if not ctx.context.get('auth'): raise PublicError('UNAUTHENTICATED', 'Authentication required.') response = await ai.generate(prompt=f'Summarize support ticket: {ticket_text}') if response.error: raise PublicError('UNAVAILABLE', 'Ticket summaries are busy, try again shortly') return response.text
# 4. Mount the flow router with the dependencyapp = FastAPI()app.include_router(serve_flow(summarize_ticket, context_dependency=require_caller))# POST /summarize_ticket (no Authorization header)# => 401 {"detail":"Valid bearer token required."}For a provider that works across FastAPI, Flask, and Django, pass
context_provider to genkit_fastapi_handler. It receives a
genkit.web.RequestData with lowercased headers, method, input (the
unwrapped "data" field), and the framework request. A PublicError raised
here returns its status:
from typing import Any
from fastapi import FastAPIfrom genkit import Genkit, PublicErrorfrom genkit.web import RequestDatafrom genkit_fastapi import genkit_fastapi_handlerfrom genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))app = FastAPI()
# 1. Portable ContextProvider reading lowercased headers on RequestDataasync def bearer_context(req: RequestData) -> dict[str, Any]: header = req.headers.get('authorization', '') if not header.startswith('Bearer '): raise PublicError('UNAUTHENTICATED', 'Missing bearer token.') claims = verify_jwt(header.removeprefix('Bearer ')) # your token verifier return {'auth': claims}
# 2. Serve the flow with the provider@app.post('/draft_refund_note')@genkit_fastapi_handler(ai, context_provider=bearer_context)@ai.flow()async def draft_refund_note(order_id: str) -> str: response = await ai.generate(prompt=f'Write a short refund confirmation for {order_id}.') if response.error: raise PublicError('UNAVAILABLE', 'Refund notes are busy, try again shortly') return response.text# POST /draft_refund_note (no Authorization header)# => 401 {"message":"Missing bearer token.","status":"UNAUTHENTICATED"}Flask and Django (genkit-flask, genkit-django)
Section titled “Flask and Django (genkit-flask, genkit-django)”The same ContextProvider works with genkit-flask and genkit-django. Flask
needs flask[async]; Django needs 5.0+ under ASGI:
from flask import Flaskfrom genkit import Genkit, PublicErrorfrom genkit_flask import genkit_flask_handlerfrom genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))flask_app = Flask(__name__)
# 1. Reuse bearer_context from the FastAPI example on a Flask route@flask_app.post('/draft_refund_note')@genkit_flask_handler(ai, context_provider=bearer_context)@ai.flow()async def flask_refund_note(order_id: str) -> str: response = await ai.generate(prompt=f'Confirm refund for {order_id}.') if response.error: raise PublicError('UNAVAILABLE', 'Refund notes are busy, try again shortly') return response.textfrom django.urls import pathfrom genkit import Genkit, PublicErrorfrom genkit_django import genkit_django_handlerfrom genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))
# 1. Same provider, served as an async Django view@genkit_django_handler(ai, context_provider=bearer_context)@ai.flow()async def django_refund_note(order_id: str) -> str: response = await ai.generate(prompt=f'Confirm refund for {order_id}.') if response.error: raise PublicError('UNAVAILABLE', 'Refund notes are busy, try again shortly') return response.text
urlpatterns = [path('draft_refund_note', django_refund_note)]Custom routes (genkit.web)
Section titled “Custom routes (genkit.web)”For other frameworks or hand-written routes, build a RequestData, call your
provider, and frame the response with the genkit.web helpers. See
Custom routes with genkit.web
for a full route.
Map a rejection to the right status
Section titled “Map a rejection to the right status”Raise PublicError(status, message) (from genkit import PublicError) from a
context provider or flow. The handler sends its status and message:
PublicError('UNAUTHENTICATED', ...):401, missing or invalid credentials.PublicError('PERMISSION_DENIED', ...):403, the caller lacks access.
Any other exception, including a plain GenkitError with an auth status,
returns 500 with {"message":"Internal Error","status":"INTERNAL"}; the detail
stays in your server logs. A FastAPI HTTPException, Flask abort(...), or
Django PermissionDenied raised in a context provider keeps the framework’s
response. See Errors and timeouts.
Authorize inside the flow
Section titled “Authorize inside the flow”Putting the check inside the flow body protects both HTTP requests and direct
in-process callers (await flow.run(...) or flow.stream(...)). Accept
ctx: FlowContext as the second parameter of @ai.flow(), or call
Genkit.current_context() inside shared helper functions:
import asynciofrom pydantic import BaseModelfrom genkit import FlowContext, Genkit, PublicError
ai = Genkit()
class RefundInput(BaseModel): account_id: str amount_cents: int
# 1. Check both authentication and resource ownership inside the flow@ai.flow()async def issue_refund(req: RefundInput, ctx: FlowContext) -> str: auth = ctx.context.get('auth') if not auth: raise PublicError('UNAUTHENTICATED', 'Sign-in required.') if auth.get('account_id') != req.account_id and auth.get('role') != 'admin': raise PublicError('PERMISSION_DENIED', 'Cannot issue refunds for another account.') return f'Refunded {req.amount_cents} cents to {req.account_id}'
# 2. Pass context explicitly when calling in-process or in testsasync def main() -> None: result = await issue_refund.run( RefundInput(account_id='acct_42', amount_cents=1500), context={'auth': {'account_id': 'acct_42', 'role': 'member'}}, ) print(result.response) # => Refunded 1500 cents to acct_42
asyncio.run(main())For streaming callers, pass context= to .stream(...) the same way:
stream = issue_refund.stream(RefundInput(...), context={'auth': claims}).
When testing locally in the Developer UI, populate the Auth JSON pane (or
pass --context on the CLI) to supply ctx.context.
Scope tool calls to the caller
Section titled “Scope tool calls to the caller”Prompt injection can steer a model into requesting another user’s records if a
tool accepts user_id or tenant_id as an LLM-supplied input field. Omit
caller identity from the tool’s input schema and read it from ToolContext
instead:
from pydantic import BaseModel, Fieldfrom genkit import Genkit, PublicError, ToolContextfrom genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))
class OrderLookupInput(BaseModel): status: str = Field(description='Order status filter such as open or shipped')
# 1. Read caller identity from ToolContext, never from model arguments@ai.tool(description='List orders belonging to the signed-in customer.')async def list_my_orders(input: OrderLookupInput, ctx: ToolContext) -> list[dict[str, str]]: uid = ctx.context.get('auth', {}).get('uid') if not uid: raise PublicError('UNAUTHENTICATED', 'No signed-in customer.') return await order_store.list_for_user(uid=uid, status=input.status)Apply the same pattern inside custom retrievers: filter vector or database
queries by tenant ID from ctx.context, never from a filter string produced by
the model.
Verify the client, not just the user
Section titled “Verify the client, not just the user”Authenticating the end user does not stop a scraper replaying your endpoint with
a stolen token, and some deployments have no end user at all. For those, add a
check on the calling application: a service-to-service identity token, a signed
request from your own frontend, or App Check-style attestation. Put it in the
same context_dependency or context_provider, as a second gate before the
user check.
Deployment notes
Section titled “Deployment notes”- Cloud Run IAM vs. application auth: Deploy without
--allow-unauthenticatedwhen callers are Google Cloud services or workloads that can present IAM identity tokens, keeping unauthenticated requests off your container completely. For end-user bearer tokens, enforce authentication incontext_dependencyorcontext_provider. See Deploy with Cloud Run. - Keep the Developer UI reflection server off in production: The reflection
server runs any registered action. It starts only when
GENKIT_ENV=devorGENKIT_REFLECTION_ENABLED=true, and requires a secret only whenGENKIT_REFLECTION_SECRET_TOKENis set. Keep it off on public containers, or set the secret; see Developer tools. - Return
response.textorresponse.outputfrom served flows, never a rawModelResponse; itsrequestfield carries your system prompt and tool definitions. See Backend frameworks. - Agent HTTP routes:
serve_agent(from genkit_fastapi.exp import serve_agent) takes the samecontext_dependencyasserve_flow; see Serve agents over HTTP.
Learn more
Section titled “Learn more”- Errors and timeouts: the full HTTP status mapping and what reaches a client
- Error types: the status set behind
PublicError