Skip to content

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 context dict 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 internal GenkitError instances are redacted to generic 500 responses on the wire.

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 hmac
import os
from typing import Any
from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from genkit import FlowContext, Genkit, PublicError
from genkit_fastapi import serve_flow
from genkit_google_genai import GoogleAI
# 1. Initialize Genkit
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))
bearer_scheme = HTTPBearer(auto_error=False)
# 2. Verify the caller in a FastAPI dependency
async 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 dependency
app = 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 FastAPI
from genkit import Genkit, PublicError
from genkit.web import RequestData
from genkit_fastapi import genkit_fastapi_handler
from genkit_google_genai import GoogleAI
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))
app = FastAPI()
# 1. Portable ContextProvider reading lowercased headers on RequestData
async 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 Flask
from genkit import Genkit, PublicError
from genkit_flask import genkit_flask_handler
from 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.text
from django.urls import path
from genkit import Genkit, PublicError
from genkit_django import genkit_django_handler
from 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)]

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.

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.

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 asyncio
from pydantic import BaseModel
from 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 tests
async 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.

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, Field
from genkit import Genkit, PublicError, ToolContext
from 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.

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.

  • Cloud Run IAM vs. application auth: Deploy without --allow-unauthenticated when 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 in context_dependency or context_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=dev or GENKIT_REFLECTION_ENABLED=true, and requires a secret only when GENKIT_REFLECTION_SECRET_TOKEN is set. Keep it off on public containers, or set the secret; see Developer tools.
  • Return response.text or response.output from served flows, never a raw ModelResponse; its request field carries your system prompt and tool definitions. See Backend frameworks.
  • Agent HTTP routes: serve_agent (from genkit_fastapi.exp import serve_agent) takes the same context_dependency as serve_flow; see Serve agents over HTTP.