webex_byova
webex_byova
Webex BYOVA / BYODS Python SDK.
BYOVA
Webex BYOVA / BYODS Python SDK facade.
Central entry point that wires Integration OAuth, Service App token management, webhook registration, per-org API clients, and JWS verification.
Example
sdk = BYOVA(integration=..., service_app=...)
await sdk.integration.aauthorize()
client = await sdk.aget_client_for_org(org_id)
config
property
config: BYOVAConfig
Global SDK configuration.
integration
property
integration: IntegrationTokenManager
Integration OAuth token manager.
service_app
property
service_app: ServiceAppTokenManager
Service App token manager for per-org tokens.
webhooks
property
webhooks: WebhookManager
Webhook registration and management.
__init__
__init__(integration: IntegrationCredentials, service_app: ServiceAppCredentials, *, config: BYOVAConfig | None = None, token_storage: TokenStorage | None = None) -> None
Initialize the BYOVA SDK client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
integration
|
IntegrationCredentials
|
Integration OAuth credentials. |
required |
service_app
|
ServiceAppCredentials
|
Service App OAuth credentials. |
required |
config
|
BYOVAConfig | None
|
Optional global SDK configuration. |
None
|
token_storage
|
TokenStorage | None
|
Token persistence backend; defaults to in-memory storage. |
None
|
from_env
classmethod
from_env(*, config: BYOVAConfig | None = None) -> BYOVA
Construct a client from WEBEX_* environment variables.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
BYOVAConfig | None
|
Optional global SDK configuration. |
None
|
Returns:
| Type | Description |
|---|---|
BYOVA
|
Configured |
Raises:
| Type | Description |
|---|---|
ValueError
|
If required environment variables are missing. |
get_client_for_org
get_client_for_org(org_id: str) -> OrgClient
Return a per-org client for DataSource operations (sync).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
str
|
Organization UUID. |
required |
Returns:
| Type | Description |
|---|---|
OrgClient
|
|
Raises:
| Type | Description |
|---|---|
OrgNotRegisteredError
|
If no Service App tokens exist for the org. |
aget_client_for_org
async
aget_client_for_org(org_id: str) -> OrgClient
Return a per-org client for DataSource and Schema operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
str
|
Organization UUID. |
required |
Returns:
| Type | Description |
|---|---|
OrgClient
|
|
Raises:
| Type | Description |
|---|---|
OrgNotRegisteredError
|
If no Service App tokens exist for the org. |
ahandle_service_app_webhook
async
ahandle_service_app_webhook(payload: dict[str, Any]) -> ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
Process a serviceApp authorized or deauthorized webhook.
On authorization, fetches and stores Service App tokens for the org. On deauthorization, removes stored tokens.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
dict[str, Any]
|
Raw webhook JSON from Webex. |
required |
Returns:
| Type | Description |
|---|---|
ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
|
|
Raises:
| Type | Description |
|---|---|
ValidationError
|
If the payload is not a valid serviceApp event. |
handle_service_app_webhook
handle_service_app_webhook(payload: dict[str, Any]) -> ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
Process a serviceApp webhook (sync wrapper).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
dict[str, Any]
|
Raw webhook JSON from Webex. |
required |
Returns:
| Type | Description |
|---|---|
ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
|
Authorization or deauthorization result. |
verify_jws_token
verify_jws_token(jws_token: str) -> dict[str, Any]
Verify an inbound BYODS JWS token (sync).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
jws_token
|
str
|
JWS token string from Webex data delivery. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Decoded JWT claims dictionary. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the token is invalid or no matching JWK is found. |
averify_jws_token
async
averify_jws_token(jws_token: str) -> dict[str, Any]
Verify an inbound BYODS JWS token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
jws_token
|
str
|
JWS token string from Webex data delivery. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Decoded JWT claims dictionary. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the token is invalid or no matching JWK is found. |
close
close() -> None
Close the underlying HTTP client and release connections.
aclose
async
aclose() -> None
Close the underlying HTTP client asynchronously.
BYOVAConfig
dataclass
Global SDK configuration for Webex API endpoints and behavior.
Attributes:
| Name | Type | Description |
|---|---|---|
base_url |
str
|
Base URL for Webex REST API requests. |
authorize_url |
str
|
OAuth authorization endpoint. |
token_url |
str
|
OAuth token exchange and refresh endpoint. |
jwk_url_us |
str
|
JWK verification URL for US region. |
jwk_url_eu |
str
|
JWK verification URL for EU region. |
region |
str
|
Active region for JWK lookup ( |
timeout |
float
|
HTTP request timeout in seconds. |
jwk_url
property
jwk_url: str
Return the JWK URL for the configured region.
Returns:
| Type | Description |
|---|---|
str
|
JWK verification URL for |
AuthenticationError
NotFoundError
RateLimitError
Bases: WebexBYOVAError
Raised when the Webex API rate limit is exceeded (HTTP 429).
Attributes:
| Name | Type | Description |
|---|---|---|
retry_after |
Seconds to wait before retrying, from the |
__init__
__init__(message: str, *, status_code: int | None = 429, body: Any = None, retry_after: int | None = None) -> None
Initialize the rate limit exception.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
status_code
|
int | None
|
HTTP status code (defaults to 429). |
429
|
body
|
Any
|
Raw response body from the failed request. |
None
|
retry_after
|
int | None
|
Recommended retry delay in seconds. |
None
|
ValidationError
WebexBYOVAError
Bases: Exception
Base exception for all SDK errors.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status code from the Webex API, if applicable. |
|
body |
Raw response body from the Webex API, if available. |
__init__
__init__(message: str, *, status_code: int | None = None, body: Any = None) -> None
Initialize the exception.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable error description. |
required |
status_code
|
int | None
|
HTTP status code from the failed request. |
None
|
body
|
Any
|
Parsed or raw response body from the failed request. |
None
|
BYOVAMediaServer
Developer-hosted BYOVA gRPC media server.
from_env
classmethod
from_env() -> BYOVAMediaServer
Construct server from WEBEX_MEDIA_* environment variables.
on
on(event: str) -> Callable[[Handler], Handler]
Decorator to register an async or sync event handler.
handler
handler(event: str) -> Callable[[Handler], Handler]
Alias for :meth:on.
use_proxy
use_proxy(connector: Any) -> None
Attach a WebSocket proxy connector.
start
async
start() -> None
Bind and start the gRPC server.
stop
async
stop(grace: float = 5.0) -> None
Gracefully stop the server.
serve
async
serve() -> None
Start the server and wait until interrupted.
MediaServerConfig
Bases: BaseModel
Validated server-wide settings for the BYOVA media server.
chunk_bytes
property
chunk_bytes: int
Raw μ-law bytes per outbound chunk.
from_env
classmethod
from_env() -> MediaServerConfig
Build configuration from WEBEX_MEDIA_* environment variables.
webex_byova.client.BYOVA
Webex BYOVA / BYODS Python SDK facade.
Central entry point that wires Integration OAuth, Service App token management, webhook registration, per-org API clients, and JWS verification.
Example
sdk = BYOVA(integration=..., service_app=...)
await sdk.integration.aauthorize()
client = await sdk.aget_client_for_org(org_id)
_config
instance-attribute
_config = config or BYOVAConfig()
_storage
instance-attribute
_storage: TokenStorage = token_storage or InMemoryTokenStorage()
_http
instance-attribute
_http = HttpClient(_config)
_integration
instance-attribute
_integration = IntegrationTokenManager(integration, _http, _storage, _config)
_service_app
instance-attribute
_service_app = ServiceAppTokenManager(service_app, _integration, _http, _storage)
_webhooks
instance-attribute
_webhooks = WebhookManager(_integration, _http)
_jws
instance-attribute
_jws = JWSVerifier(_config)
config
property
config: BYOVAConfig
Global SDK configuration.
integration
property
integration: IntegrationTokenManager
Integration OAuth token manager.
service_app
property
service_app: ServiceAppTokenManager
Service App token manager for per-org tokens.
webhooks
property
webhooks: WebhookManager
Webhook registration and management.
__init__
__init__(integration: IntegrationCredentials, service_app: ServiceAppCredentials, *, config: BYOVAConfig | None = None, token_storage: TokenStorage | None = None) -> None
Initialize the BYOVA SDK client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
integration
|
IntegrationCredentials
|
Integration OAuth credentials. |
required |
service_app
|
ServiceAppCredentials
|
Service App OAuth credentials. |
required |
config
|
BYOVAConfig | None
|
Optional global SDK configuration. |
None
|
token_storage
|
TokenStorage | None
|
Token persistence backend; defaults to in-memory storage. |
None
|
from_env
classmethod
from_env(*, config: BYOVAConfig | None = None) -> BYOVA
Construct a client from WEBEX_* environment variables.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
BYOVAConfig | None
|
Optional global SDK configuration. |
None
|
Returns:
| Type | Description |
|---|---|
BYOVA
|
Configured |
Raises:
| Type | Description |
|---|---|
ValueError
|
If required environment variables are missing. |
get_client_for_org
get_client_for_org(org_id: str) -> OrgClient
Return a per-org client for DataSource operations (sync).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
str
|
Organization UUID. |
required |
Returns:
| Type | Description |
|---|---|
OrgClient
|
|
Raises:
| Type | Description |
|---|---|
OrgNotRegisteredError
|
If no Service App tokens exist for the org. |
aget_client_for_org
async
aget_client_for_org(org_id: str) -> OrgClient
Return a per-org client for DataSource and Schema operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
str
|
Organization UUID. |
required |
Returns:
| Type | Description |
|---|---|
OrgClient
|
|
Raises:
| Type | Description |
|---|---|
OrgNotRegisteredError
|
If no Service App tokens exist for the org. |
ahandle_service_app_webhook
async
ahandle_service_app_webhook(payload: dict[str, Any]) -> ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
Process a serviceApp authorized or deauthorized webhook.
On authorization, fetches and stores Service App tokens for the org. On deauthorization, removes stored tokens.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
dict[str, Any]
|
Raw webhook JSON from Webex. |
required |
Returns:
| Type | Description |
|---|---|
ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
|
|
Raises:
| Type | Description |
|---|---|
ValidationError
|
If the payload is not a valid serviceApp event. |
handle_service_app_webhook
handle_service_app_webhook(payload: dict[str, Any]) -> ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
Process a serviceApp webhook (sync wrapper).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
dict[str, Any]
|
Raw webhook JSON from Webex. |
required |
Returns:
| Type | Description |
|---|---|
ServiceAppAuthorizedResult | ServiceAppDeauthorizedResult
|
Authorization or deauthorization result. |
verify_jws_token
verify_jws_token(jws_token: str) -> dict[str, Any]
Verify an inbound BYODS JWS token (sync).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
jws_token
|
str
|
JWS token string from Webex data delivery. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Decoded JWT claims dictionary. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the token is invalid or no matching JWK is found. |
averify_jws_token
async
averify_jws_token(jws_token: str) -> dict[str, Any]
Verify an inbound BYODS JWS token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
jws_token
|
str
|
JWS token string from Webex data delivery. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Decoded JWT claims dictionary. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the token is invalid or no matching JWK is found. |
close
close() -> None
Close the underlying HTTP client and release connections.
aclose
async
aclose() -> None
Close the underlying HTTP client asynchronously.
webex_byova.config.BYOVAConfig
dataclass
Global SDK configuration for Webex API endpoints and behavior.
Attributes:
| Name | Type | Description |
|---|---|---|
base_url |
str
|
Base URL for Webex REST API requests. |
authorize_url |
str
|
OAuth authorization endpoint. |
token_url |
str
|
OAuth token exchange and refresh endpoint. |
jwk_url_us |
str
|
JWK verification URL for US region. |
jwk_url_eu |
str
|
JWK verification URL for EU region. |
region |
str
|
Active region for JWK lookup ( |
timeout |
float
|
HTTP request timeout in seconds. |
base_url
class-attribute
instance-attribute
base_url: str = 'https://webexapis.com/v1'
authorize_url
class-attribute
instance-attribute
authorize_url: str = 'https://webexapis.com/v1/authorize'
token_url
class-attribute
instance-attribute
token_url: str = 'https://webexapis.com/v1/access_token'
jwk_url_us
class-attribute
instance-attribute
jwk_url_us: str = 'https://idbroker.webex.com/idb/oauth2/v2/keys/verificationjwk'
jwk_url_eu
class-attribute
instance-attribute
jwk_url_eu: str = 'https://idbroker-eu.webex.com/idb/oauth2/v2/keys/verificationjwk'
region
class-attribute
instance-attribute
region: str = 'us'
timeout
class-attribute
instance-attribute
timeout: float = 30.0
jwk_url
property
jwk_url: str
Return the JWK URL for the configured region.
Returns:
| Type | Description |
|---|---|
str
|
JWK verification URL for |
__init__
__init__(base_url: str = 'https://webexapis.com/v1', authorize_url: str = 'https://webexapis.com/v1/authorize', token_url: str = 'https://webexapis.com/v1/access_token', jwk_url_us: str = 'https://idbroker.webex.com/idb/oauth2/v2/keys/verificationjwk', jwk_url_eu: str = 'https://idbroker-eu.webex.com/idb/oauth2/v2/keys/verificationjwk', region: str = 'us', timeout: float = 30.0) -> None