google-adk-auth

name	google-adk-auth
description	ADK authentication and credentials. Use when adding auth to tools — API keys, bearer tokens, OAuth2 flows, OpenID Connect, service accounts, and credential storage services.

Google ADK — Authentication & Credentials

Overview

ADK's auth system connects tools to authenticated APIs. It handles credential construction, OAuth2 flows, and credential persistence.

Component	Purpose
AuthCredential	Holds the secret (key, token, OAuth2 tokens, service account)
AuthScheme	Describes HOW auth is applied (header, query, OAuth2 flow)
AuthConfig	Pairs scheme + credential for a tool's auth requirement
Credential Services	Persist credentials across invocations
Auth Helpers	Convenience builders for common patterns

Imports

from google.adk.auth import (
    AuthCredential,
    AuthCredentialTypes,
    AuthScheme,
    AuthSchemeType,
    AuthConfig,
    OAuth2Auth,
    OpenIdConnectWithConfig,
)
from google.adk.auth.auth_credential import (
    HttpAuth,
    HttpCredentials,
    ServiceAccount,
    ServiceAccountCredential,
)
from google.adk.auth.credential_service.in_memory_credential_service import InMemoryCredentialService
from google.adk.auth.credential_service.session_state_credential_service import SessionStateCredentialService
from google.adk.tools.openapi_tool.auth.auth_helpers import (
    token_to_scheme_credential,
    service_account_scheme_credential,
    service_account_dict_to_scheme_credential,
    openid_dict_to_scheme_credential,
    openid_url_to_scheme_credential,
)

AuthCredential Types

API Key

credential = AuthCredential(
    auth_type=AuthCredentialTypes.API_KEY,
    api_key="your-api-key-here",
)

HTTP Bearer Token

credential = AuthCredential(
    auth_type=AuthCredentialTypes.HTTP,
    http=HttpAuth(
        scheme="bearer",
        credentials=HttpCredentials(token="eyJhbGciOi..."),
    ),
)

HTTP Basic Auth

credential = AuthCredential(
    auth_type=AuthCredentialTypes.HTTP,
    http=HttpAuth(
        scheme="basic",
        credentials=HttpCredentials(username="user", password="pass"),
    ),
)

OAuth2 (Authorization Code Flow)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.OAUTH2,
    oauth2=OAuth2Auth(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

OpenID Connect

credential = AuthCredential(
    auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
    oauth2=OAuth2Auth(
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://example.com/callback",
    ),
)

Service Account (JSON Key)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        service_account_credential=ServiceAccountCredential(
            type_="service_account",
            project_id="my-project",
            private_key_id="key-id",
            private_key="-----BEGIN PRIVATE KEY-----\n...",
            client_email="[e-mail]",
            client_id="123456",
            auth_uri="https://accounts.google.com/o/oauth2/auth",
            token_uri="https://oauth2.googleapis.com/token",
            auth_provider_x509_cert_url="https://www.googleapis.com/oauth2/v1/certs",
            client_x509_cert_url="https://www.googleapis.com/robot/v1/metadata/x509/...",
            universe_domain="googleapis.com",
        ),
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    ),
)

Service Account (Application Default Credentials)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        use_default_credential=True,
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    ),
)

Service Account (ID Token for Cloud Run)

credential = AuthCredential(
    auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
    service_account=ServiceAccount(
        use_default_credential=True,
        use_id_token=True,
        audience="https://my-service-xyz.run.app",
    ),
)

Auth Helpers (Convenience Builders)

API Key via Helper

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

# API Key in header
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "header", "X-API-Key", "your-key-value"
)

# API Key in query parameter
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "query", "api_key", "your-key-value"
)

Bearer Token via Helper

auth_scheme, auth_credential = token_to_scheme_credential(
    "oauth2Token", "header", "Authorization", "your-bearer-token"
)

Service Account via Helper

from google.adk.tools.openapi_tool.auth.auth_helpers import service_account_scheme_credential

auth_scheme, auth_credential = service_account_scheme_credential(
    ServiceAccount(
        use_default_credential=True,
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    )
)

OpenID Connect via Discovery URL

from google.adk.tools.openapi_tool.auth.auth_helpers import openid_url_to_scheme_credential

auth_scheme, auth_credential = openid_url_to_scheme_credential(
    openid_url="https://accounts.google.com/.well-known/openid-configuration",
    scopes=["openid", "email", "profile"],
    credential_dict={
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "redirect_uri": "https://example.com/callback",
    },
)

Integration with OpenAPIToolset

from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential

# Create auth scheme and credential
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "header", "X-API-Key", "sk-live-xxx"
)

# Pass to OpenAPIToolset
toolset = OpenAPIToolset(
    spec_str=open("openapi.yaml").read(),
    spec_str_type="yaml",
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)

agent = Agent(
    name="api_agent",
    model="gemini-2.5-flash",
    instruction="Call the API.",
    tools=[*toolset.get_tools()],
)

OAuth2 with OpenAPIToolset

from google.adk.auth import AuthCredential, AuthCredentialTypes, OAuth2Auth

toolset = OpenAPIToolset(
    spec_str=spec_str,
    spec_str_type="json",
    auth_scheme=auth_scheme,
    auth_credential=AuthCredential(
        auth_type=AuthCredentialTypes.OAUTH2,
        oauth2=OAuth2Auth(
            client_id="your-client-id",
            client_secret="your-client-secret",
        ),
    ),
    credential_key="my_oauth_cred",
)

Credential Services

Credential services persist exchanged credentials so users don't re-authenticate every invocation.

InMemoryCredentialService (Development)

from google.adk.auth.credential_service.in_memory_credential_service import InMemoryCredentialService

credential_service = InMemoryCredentialService()

SessionStateCredentialService (Session-Backed)

Stores credentials in session state. Simple but not secure for production.

from google.adk.auth.credential_service.session_state_credential_service import SessionStateCredentialService

credential_service = SessionStateCredentialService()

Wiring Credential Service to Runner

from google.adk.runners import Runner

runner = Runner(
    agent=agent,
    session_service=session_service,
    app_name="my_app",
)
# Note: credential_service is passed to the agent's auth handler,
# not directly to the Runner. It's used internally by the auth system.

AuthConfig (Tool Auth Requirements)

AuthConfig pairs a scheme with credentials. Used internally when tools require authentication:

from google.adk.auth import AuthConfig, AuthScheme

auth_config = AuthConfig(
    auth_scheme=auth_scheme,
    raw_auth_credential=auth_credential,
    credential_key="unique_key_for_caching",
)

Fields:

• auth_scheme — How auth is applied (SecurityScheme from OpenAPI)
• raw_auth_credential — Initial credential (e.g., client_id + secret for OAuth2)
• exchanged_auth_credential — Final usable credential (e.g., access token after OAuth2 exchange)
• credential_key — Stable key for credential storage/retrieval

AuthScheme Types

AuthScheme uses FastAPI's OpenAPI security models:

from fastapi.openapi.models import APIKey, APIKeyIn, HTTPBearer, OAuth2, OAuthFlows

# API Key in header
scheme = APIKey(**{"type": "apiKey", "in": APIKeyIn.header, "name": "X-API-Key"})

# Bearer token
scheme = HTTPBearer(bearerFormat="JWT")

# OAuth2 Authorization Code
scheme = OAuth2(flows=OAuthFlows(
    authorizationCode={
        "authorizationUrl": "https://example.com/auth",
        "tokenUrl": "https://example.com/token",
        "scopes": {"read": "Read access"},
    }
))

Key Rules

• AuthCredentialTypes enum values: API_KEY, HTTP, OAUTH2, OPEN_ID_CONNECT, SERVICE_ACCOUNT
• OpenID Connect uses oauth2 field (same as OAuth2) but with auth_type=OPEN_ID_CONNECT
• Service Account requires either service_account_credential OR use_default_credential=True
• When use_id_token=True, audience is required (target service URL)
• Auth helpers return Tuple[AuthScheme, AuthCredential] — pass both to OpenAPIToolset
• Credential services are experimental (@experimental decorator)
• credential_key enables credential caching — same key = same stored credential
• The auth system auto-generates credential_key from scheme + credential if not provided

Related Skills

• google-adk-openapi-tool — OpenAPIToolset where auth is most commonly used
• google-adk-callbacks — before_tool_callback can enforce auth checks
• google-adk-session — Session services (SessionStateCredentialService stores in session)