Token and Authentication API Reference

This page documents the authentication and token management components.

Authentication

bws_sdk.token.Auth(client_token, region, state_file=None)

Main authentication handler for the BWS SDK.

This class manages OAuth authentication with the BWS API, including token refresh, state file management, and organization encryption key handling. It provides automatic token refresh and persistent authentication state.

Attributes:

Name	Type	Description
state_file	Path | None	Optional path to the state file for token persistence
region	Region	The BWS region configuration
client_token	ClientToken	The client authentication token
oauth_jwt	dict	Decoded OAuth JWT token information
org_enc_key	SymmetricCryptoKey	Organization encryption key

Initialize the Auth instance.

Parameters:

Name	Type	Description	Default
client_token	ClientToken	The client authentication token	required
region	Region	The BWS region configuration	required
state_file	str | None	Optional path to state file for token persistence	None

Raises:

Type	Description
BWSSDKError	If authentication fails
InvalidIdentityResponseError	If the identity response is invalid
SendRequestError	If the network request fails
UnauthorisedTokenError	If the token is invalid or expired
ApiError	If the API returns an error response

bearer_token property

Get the current bearer token, refreshing if necessary.

Checks if the current token is expired (within 60 seconds of expiry) and automatically refreshes it if needed.

Returns:

Name	Type	Description
str	str	The current valid bearer token

Raises:

Type	Description
InvalidIdentityResponseError	If token refresh fails due to invalid response
SendRequestError	If the network request for token refresh fails
UnauthorisedTokenError	If the token is invalid during refresh
ApiError	If the API returns an error during refresh

org_id property

Get the organization ID from the OAuth JWT token.

Returns:

Name	Type	Description
str	str	The organization identifier

Raises:

Type	Description
KeyError	If the JWT token doesn't contain organization information

from_token(token_str, region, state_file_path=None) classmethod

Create an Auth instance from a token string.

Factory method that creates a ClientToken from the provided token string and initializes an Auth instance with it.

Parameters:

Name	Type	Description	Default
token_str	str	The BWS token string to parse	required
region	Region	The BWS region configuration	required
state_file_path	str | None	Optional path to state file for token persistence	None

Returns:

Name	Type	Description
Auth	Auth	A new Auth instance

Raises:

Type	Description
InvalidTokenError	If the token version is unsupported or format is invalid
BWSSDKError	If authentication fails during initialization
InvalidIdentityResponseError	If the identity response is invalid
SendRequestError	If the network request fails
UnauthorisedTokenError	If the token is invalid or expired
ApiError	If the API returns an error response

Token Types

bws_sdk.token.ClientToken(access_token_id, client_secret, encryption_key)

Represents a BWS client authentication token.

This class encapsulates the client token components required for authenticating with the BWS API, including the access token ID, client secret, and encryption key.

Attributes:

Name	Type	Description
access_token_id	str	The unique identifier for the access token
client_secret	str	The client secret for authentication
encryption_key	SymmetricCryptoKey	The encryption key for data encryption/decryption

Initialize a ClientToken instance.

Parameters:

Name	Type	Description	Default
access_token_id	str	The unique identifier for the access token	required
client_secret	str	The client secret for authentication	required
encryption_key	SymmetricCryptoKey	The encryption key for data encryption/decryption	required

from_str(token_str) classmethod

Create a ClientToken instance from a token string.

Parses a BWS token string in the format "version.access_token_id.client_secret:encryption_key" and creates a ClientToken instance with the extracted components.

Parameters:

Name	Type	Description	Default
token_str	str	The BWS token string to parse	required

Returns:

Name	Type	Description
ClientToken	ClientToken	A new ClientToken instance

Raises:

Type	Description
InvalidTokenError	If the token version is unsupported (not "0")
InvalidTokenError	If the encryption key length is invalid (not 16 bytes)
ValueError	If the token string format is invalid or cannot be split properly

bws_sdk.token.IdentityRequest

Bases: BaseModel

Model for OAuth identity requests to the BWS API.

This Pydantic model represents the data structure required for authentication requests to obtain OAuth tokens from the BWS identity service.

Attributes:

Name	Type	Description
scope	str	The OAuth scope for the request (default: "api.secrets")
grant_type	str	The OAuth grant type (default: "client_credentials")
client_id	str	The client identifier for authentication
client_secret	str	The client secret for authentication

to_query_string()

Convert the identity request to a URL-encoded query string.

Returns:

Name	Type	Description
str	str	URL-encoded string representation of the request data