Inbound authentication

Inbound authentication verifies the identity of requests coming into the agent. VeADK supports API keys and OAuth2.

API key authentication

An API key verifies the caller’s identity and authorizes access to API resources with a single string secret. VeADK passes the API key in the URL’s token parameter.

API keys apply only to the A2A / MCP Server deployment mode; they are not recommended for the VeADK Web mode, which should use OAuth2 instead.

Select API-key auth when scaffolding an agent, or add --auth-method=api-key when deploying an existing project. The API gateway then validates the API key carried in the token URL parameter on each request.

OAuth2 single sign-on

OAuth2 is an open authorization framework: instead of exposing account credentials, it grants limited access via tokens, so a single login lets users reach multiple related applications without re-authenticating. VeADK offers two integration paths:

Path	When to use	Notes
API gateway	VeFaaS cloud deployment	Deployed via scaffolding; the API gateway handles auth
Starlette / FastAPI middleware	Local dev / self-hosted	Integrate the OAuth2 middleware in the app

API gateway

For VeADK Web apps deployed on VeFaaS, where the API gateway runs the OAuth2 flow.

The API gateway mode requires API gateway version 4.0.0 or later.

Select OAuth2 when scaffolding an agent, or add --auth-method=oauth2 when deploying an existing project; VeADK creates the Identity user pool and client for you. To reuse existing resources, pass --user-pool-name and --client-name at deploy time. After deploying, create users in Agent Identity:

Open the user pool

In the Volcengine console, go to Agent Identity, select Authentication › User Pools, and choose your pool.

Create a user

On the pool’s Users tab, click New User, fill in the details, and confirm.

When a user visits the app, the API gateway guides them through login; afterwards you can read the user’s JWT from the Authorization header.

Starlette / FastAPI middleware

For local development or self-hosted deployment, VeADK’s middleware handles OAuth2 inside the app and supports any Starlette-based framework (including FastAPI). Prefer OAuth2Config.from_veidentity(), which auto-configures a VeIdentity user pool:

from fastapi import FastAPI
from veadk.auth.middleware.oauth2_auth import OAuth2Config, setup_oauth2

app = FastAPI()

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="my-app",
        client_name="my-app-web",
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

This creates the user pool and client (if missing), registers the callback URL, and configures the OAuth2 endpoints. Starlette usage is identical — swap FastAPI() for Starlette(). To reuse existing resources, disable auto-creation:

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="existing-pool",
        client_name="existing-client",
        redirect_uri="https://myapp.com/oauth2/callback",
        auto_create=False,             # error if the resource doesn't exist
        auto_register_callback=False,  # don't modify the callback URL
    ),
)

Local development needs HTTPS cookies disabled:

setup_oauth2(
    app,
    OAuth2Config.from_veidentity(
        user_pool_name="my-app",
        client_name="my-app-web",
        redirect_uri="http://localhost:8000/oauth2/callback",
        cookie_secure=False,  # local HTTP development
    ),
)

To use an OAuth2 provider other than VeIdentity, construct OAuth2Config directly:

setup_oauth2(
    app,
    OAuth2Config(
        authorize_url="https://provider.com/oauth2/authorize",
        token_url="https://provider.com/oauth2/token",
        userinfo_url="https://provider.com/oauth2/userinfo",
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://myapp.com/oauth2/callback",
    ),
)

The middleware registers these routes automatically:

Route	Description
`/oauth2/login`	Start the OAuth2 login flow
`/oauth2/callback`	Handle the OAuth2 callback
`/oauth2/logout`	Log out and clear the session
`/oauth2/userinfo`	Get the current user’s info

You can exempt paths from auth: exempt_paths=["/health", "/metrics"] (exact match) and exempt_prefixes=["/public/", "/static/"] (prefix match). The middleware responds by request type: browser requests redirect to the login page; API requests get a 401. API requests are detected via the Accept: application/json header, a path prefix (default /api/), or the X-Requested-With: XMLHttpRequest header, and can be customized with api_path_prefixes. Key OAuth2Config.from_veidentity() parameters:

Parameter	Default	Description
`user_pool_name`	required	VeIdentity user pool name
`client_name`	required	User pool client name
`redirect_uri`	required	OAuth2 callback URL
`auto_create`	`True`	Create resources if missing
`auto_register_callback`	`True`	Register the callback URL automatically
`client_type`	`WEB_APPLICATION`	Client type
`scope`	`"openid profile email"`	OAuth2 scope

Key OAuth2Config parameters:

Parameter	Default	Description
`userinfo_url`	`None`	User info endpoint URL; when configured, the middleware fetches user info from this endpoint and stores it in the session
`user_id_field`	`"sub"`	Field name used to extract the user identifier from the user info response
`session_timeout_seconds`	`3600`	Session timeout (seconds)
`cookie_secure`	`True`	Enable secure cookies
`auto_refresh_token`	`True`	Refresh tokens automatically
`token_refresh_threshold_seconds`	`300`	Token refresh threshold (seconds)
`api_path_prefixes`	`["/api/"]`	API path prefixes

When fetching user info from the userinfo endpoint, only fields safe to store in a browser session cookie are retained: sub, email, email_verified, name, given_name, family_name, preferred_username, picture, locale, updated_at, plus the field configured via user_id_field. Only values of type string, integer, float, or boolean are kept, to prevent the session cookie from exceeding browser size limits. The /oauth2/userinfo endpoint returns these filtered fields.

The default InMemoryStateStore fits single-process deployments only. For distributed setups, implement a state store backed by Redis or similar and pass it via setup_oauth2(app, config, state_store=...).

OAuth2 JWT authentication

OAuth2 JWT auth combines the OAuth2 framework with JWT, carrying the authorization token as a JWT. It applies to A2A / MCP Server. Select OAuth2 when scaffolding an agent, or add --auth-method=oauth2 when deploying; VeADK creates the Identity user pool, or reuses one via --user-pool-name. Then create an M2M client in the pool and exchange its credentials for a JWT:

REGION="cn-beijing"
USER_POOL_ID="FILL_IN_YOUR_USER_POOL_ID"
CLIENT_ID="FILL_IN_YOUR_CLIENT_ID"
CLIENT_SECRET="FILL_IN_YOUR_SECRET"

curl --location "https://userpool-${USER_POOL_ID}.userpool.auth.id.${REGION}.volces.com/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic $(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)" \
  --data-urlencode "grant_type=client_credentials"

When a user calls the app, the API gateway validates the JWT they carry; read it from the Authorization header.

Identity propagation in A2A calls

In a call chain that uses the AgentKit A2A registry, VeADK can pass credentials from the current request to a downstream agent so that it can authorize the call under the original user identity and trust context.

Credentials are sent to the resolved downstream A2A endpoint. Call only trusted downstream agents, and give inbound tokens only the permissions required for the task.

Inbound credential	Downstream behavior
`X-Ve-TIP-Token`	Forwarded to the downstream A2A agent in the same header.
`Authorization: Bearer <JWT>`	When the downstream AgentCard declares OAuth2, the Bearer JWT is preferred as the downstream `Authorization` header. Other authentication schemes are not propagated as a user JWT.

For a downstream agent that declares OAuth2, VeADK first sends the propagated Bearer JWT. It falls back to an OAuth2 M2M token and retries once only when the downstream endpoint explicitly returns 401 Unauthorized. Other status codes and call failures do not trigger M2M fallback, which prevents application or service failures from being treated as an expired identity token.

Identity propagation to the skills sandbox

When execute_skills calls the skills sandbox, it likewise forwards the inbound identity credential. VeADK reads the credential stored under the inbound_auth credential key from the credential service and sends it in the inbound_auth request header to the sandbox’s A2A endpoint, so the sandbox workflow runs under the original user identity. If the current request carries no inbound credential, the header is omitted. See the skill sandbox execution section in Code sandboxes.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

API key authentication

OAuth2 single sign-on

API gateway

Starlette / FastAPI middleware

OAuth2 JWT authentication

Identity propagation in A2A calls

Identity propagation to the skills sandbox

​API key authentication

​OAuth2 single sign-on

​API gateway

​Starlette / FastAPI middleware

​OAuth2 JWT authentication

​Identity propagation in A2A calls

​Identity propagation to the skills sandbox

API key authentication

OAuth2 single sign-on

API gateway

Starlette / FastAPI middleware

OAuth2 JWT authentication

Identity propagation in A2A calls

Identity propagation to the skills sandbox