---
title: bearer
sidebarTitle: bearer
---

# `keycardai.oauth.utils.bearer`


OAuth 2.0 Bearer Token Usage implementation (RFC 6750).

This module implements the OAuth 2.0 Bearer Token Usage specification which
describes how to use bearer tokens in HTTP requests to access protected resources.

RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
https://datatracker.ietf.org/doc/html/rfc6750

Key Features:
- Bearer token transmission methods (Authorization header, form body, query parameter)
- Token validation utilities
- Error response handling
- Security considerations implementation
- WWW-Authenticate header parsing

Transmission Methods:
1. Authorization Request Header Field (RECOMMENDED)
2. Form-Encoded Body Parameter
3. URI Query Parameter (NOT RECOMMENDED - for legacy support only)

Security Considerations:
- TLS/SSL required for all bearer token transmissions
- Token confidentiality and integrity protection
- Proper error handling without token leakage
- Cache control headers for token responses


## Functions

### `extract_bearer_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_bearer_token(authorization_header: str | None) -> str | None
```


Extract bearer token from Authorization header.

**Args:**
- `authorization_header`: Authorization header value

**Returns:**
- Bearer token or None if not found/invalid


### `validate_bearer_format` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_bearer_format(token: str) -> bool
```


Validate bearer token format per RFC 6750.

**Args:**
- `token`: Token to validate

**Returns:**
- True if format is valid


### `create_auth_header` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_auth_header(token: str) -> str
```


Create Authorization header with bearer token.

**Args:**
- `token`: Bearer token string

**Returns:**
- Formatted Authorization header value

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.1


## Classes

### `BearerTokenError` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Bearer token error response as defined in RFC 6750 Section 3.1.

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-3.1


### `BearerTokenErrors` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Standard bearer token error codes from RFC 6750 Section 3.1.

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-3.1


### `BearerToken` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Utilities for OAuth 2.0 Bearer Token handling per RFC 6750.

Provides methods for extracting, validating, and formatting bearer tokens
according to the OAuth 2.0 Bearer Token Usage specification.

Reference: https://datatracker.ietf.org/doc/html/rfc6750


**Methods:**

#### `extract_from_header` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_from_header(authorization_header: str) -> str | None
```

Extract bearer token from Authorization header.

Implements RFC 6750 Section 2.1 - Authorization Request Header Field.

**Args:**
- `authorization_header`: HTTP Authorization header value

**Returns:**
- Bearer token string or None if not found/invalid

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.1


#### `extract_from_form_body` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_from_form_body(form_data: dict[str, str]) -> str | None
```

Extract bearer token from form-encoded body parameter.

Implements RFC 6750 Section 2.2 - Form-Encoded Body Parameter.

**Args:**
- `form_data`: Form-encoded request body data

**Returns:**
- Bearer token string or None if not found

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.2


#### `extract_from_query_params` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_from_query_params(query_params: dict[str, str]) -> str | None
```

Extract bearer token from URI query parameter.

Implements RFC 6750 Section 2.3 - URI Query Parameter.

WARNING: This method is NOT RECOMMENDED due to security concerns.
Use only for legacy compatibility when other methods are not feasible.

**Args:**
- `query_params`: URI query parameters

**Returns:**
- Bearer token string or None if not found

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.3


#### `is_valid_format` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_valid_format(token: str) -> bool
```

Validate bearer token format per RFC 6750.

Checks if token conforms to the b64token ABNF rule defined in RFC 6750.

**Args:**
- `token`: Bearer token string to validate

**Returns:**
- True if token format is valid, False otherwise

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.1


#### `create_auth_header` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_auth_header(token: str) -> str
```

Create Authorization header with bearer token.

**Args:**
- `token`: Bearer token string

**Returns:**
- Formatted Authorization header value

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2.1


#### `create_www_authenticate_header` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_www_authenticate_header(realm: str | None = None, scope: str | None = None, error: str | None = None, error_description: str | None = None, error_uri: str | None = None) -> str
```

Create WWW-Authenticate header for bearer token challenges.

Used in 401 Unauthorized responses to indicate bearer token authentication
is required and provide error details if applicable.

**Args:**
- `realm`: Protection realm (optional)
- `scope`: Required OAuth 2.0 scopes
- `error`: Error code (invalid_token, invalid_request, insufficient_scope)
- `error_description`: Human-readable error description
- `error_uri`: URI for additional error information

**Returns:**
- WWW-Authenticate header value

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-3


### `BearerTokenValidator` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Bearer token format and transmission validator per RFC 6750.

Provides utilities to validate bearer token format and proper transmission
according to the security requirements in RFC 6750.

Reference: https://datatracker.ietf.org/doc/html/rfc6750


**Methods:**

#### `extract_token_from_request` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L268" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_token_from_request(headers: dict[str, str], form_data: dict[str, str] | None = None, query_params: dict[str, str] | None = None, allow_query_param: bool = False) -> str | None
```

Extract bearer token from HTTP request using RFC 6750 methods.

Tries extraction methods in order of preference:
1. Authorization header (RECOMMENDED)
2. Form-encoded body parameter
3. URI query parameter (if explicitly allowed)

**Args:**
- `headers`: HTTP request headers
- `form_data`: Form-encoded body parameters
- `query_params`: URI query parameters
- `allow_query_param`: Whether to allow query parameter method (NOT RECOMMENDED)

**Returns:**
- Extracted bearer token or None if not found

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2


#### `validate_token_transmission` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/bearer.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_token_transmission(headers: dict[str, str], form_data: dict[str, str] | None = None, query_params: dict[str, str] | None = None) -> tuple[bool, str | None]
```

Validate that token is transmitted via exactly one method.

RFC 6750 Section 2 requires that bearer tokens be transmitted using
exactly one of the defined methods to prevent ambiguity.

**Args:**
- `headers`: HTTP request headers
- `form_data`: Form-encoded body parameters
- `query_params`: URI query parameters

**Returns:**
- Tuple of (is_valid, error_message)

Reference: https://datatracker.ietf.org/doc/html/rfc6750#section-2

