# Google Adk Auth

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

- Skill: `eagleisbatman/google-adk-auth` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eagleisbatman/google-adk-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eagleisbatman/google-adk-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: eagleisbatman (https://skillmd.com/u/eagleisbatman)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/eagleisbatman/google-adk-auth

---


# 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

```python
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

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

### HTTP Bearer Token

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

### HTTP Basic Auth

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

### OAuth2 (Authorization Code Flow)

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

### OpenID Connect

```python
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)

```python
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="sa@project.iam.gserviceaccount.com",
            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)

```python
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)

```python
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

```python
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

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

### Service Account via Helper

```python
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

```python
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

```python
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

```python
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)

```python
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.

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

credential_service = SessionStateCredentialService()
```

### Wiring Credential Service to Runner

```python
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:

```python
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:

```python
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)