Client Classes and Authentication

The Airship Python Library supports multiple authentication methods through different client classes. Each client class inherits from BaseClient and provides specific authentication functionality.

Base Client

class urbanairship.client.BaseClient(key: str, location: str = 'us', timeout: int = 60, retries: int = 0, base_url: str | None = None)

Base client class for interacting with the Airship API

Parameters:

  • key – [required] An airship app key (project key) which identifies the project

  • location – [optional] The Airship cloud site the project is located in. May be ‘us’ or ‘eu’. Defaults to ‘us’.

  • timeout – [optional] An integer specifying the number of seconds used for a response timeout threshold

  • base_url – [optional] A string defining an arbitrary base_url to use for requests to the Airship API. To be used in place of location.

  • retries – [optional] An integer specifying the number of times to retry a failed request. Retried requests use exponential backoff between requests. Defaults to 0, no retry.

property location: str

location of the cloud site project belongs to. ‘us’ or ‘eu’

Basic Authentication

The BasicAuthClient is used for traditional key/secret authentication. This is the same as the deprecated Airship client class.

class urbanairship.client.BasicAuthClient(key: str, secret: str, location: str = 'us', timeout: int = 60, retries: int = 0)
Client class for interacting with the Airship API using either key and master secret

or key and application secret, depending on need.

Parameters:

  • key – [required] An Airship app key (project key) which identifies the project

  • secret – [required] An Airship application secret or master secret used to authenticate.

  • location – [optional] The Airship cloud site the project is located in. May be ‘us’ or ‘eu’. Defaults to ‘us’.

  • timeout – [optional] An integer specifying the number of seconds used for a response timeout threshold

  • retries – [optional] An integer specifying the number of times to retry a failed request. Retried requests use exponential backoff between requests. Defaults to 0, no retry.

Example usage:

import urbanairship as ua
client = ua.client.BasicAuthClient('<app key>', '<master secret>')

# Create and send a push notification
push = ua.Push(client)
push.audience = ua.all_
push.notification = ua.notification(alert='Hello, world!')
push.device_types = ua.device_types('ios', 'android')
push.send()

Bearer Token Authentication

The BearerTokenClient is used when you have an Airship-generated bearer token. This is useful when you want to manage token refresh yourself or when using tokens from other sources.

class urbanairship.client.BearerTokenClient(key: str, token: str, location: str = 'us', timeout: int = 60, retries: int = 0)

Client class for interacting with the Airship API using bearer token authentication

Parameters:

  • key – [required] An Airship app key (project key) which identifies the project

  • token – [required] An Airship-generated bearer token for the provided key.

  • location – [optional] The Airship cloud site the project is located in. May be ‘us’ or ‘eu’. Defaults to ‘us’.

  • timeout – [optional] An integer specifying the number of seconds used for a response timeout threshold

  • retries – [optional] An integer specifying the number of times to retry a failed request. Retried requests use exponential backoff between requests. Defaults to 0, no retry.

Example usage:

import urbanairship as ua
client = ua.client.BearerTokenClient('<app key>', '<bearer token>')

# Create and send a push notification
push = ua.Push(client)
push.audience = ua.all_
push.notification = ua.notification(alert='Hello, world!')
push.device_types = ua.device_types('ios', 'android')
push.send()

OAuth2 Authentication

The OAuthClient handles OAuth2 authentication using JWT assertions. It automatically manages token refresh and is recommended for production use.

class urbanairship.client.OAuthClient(key: str, client_id: str, private_key: str, location: str = 'us', scope: List[str] | None = None, ip_addr: List[str] | None = None, timeout: int = 60, retries: int = 0)

Client class for interacting with the Airship API using OAuth2 authentication with JWT assertion. Note - Not all endpoints support OAuth, and client scope may further restrict the endpoints available to a given client. See Airship API documentation for more.

Parameters:

  • key – [required] An Airship app key (project key) which identifies the project

  • client_id – [required] An Airship provided client id used to generate OAuth authentication tokens.

  • public_key – [required] The public key required to sign JWT assertions, passed as a bytestring.

  • scope – [optional] A list of scopes to which the issued token will be entitled.

  • ip_addr – [optional] A list of CIDR representations of valid IP addresses to which the issued token is restricted.

  • location – [optional] The Airship cloud site the project is located in. May be ‘us’ or ‘eu’. Defaults to ‘us’.

  • timeout – [optional] An integer specifying the number of seconds used for a response timeout threshold

  • retries – [optional] An integer specifying the number of times to retry a failed request. Retried requests use exponential backoff between requests. Defaults to 0, no retry.

Example usage:

import urbanairship as ua

# Initialize with OAuth credentials
client = ua.client.OAuthClient(
    key='<app key>',
    client_id='<client id>',
    private_key='<private key>',
    scope=['push:write', 'channels:read']  # Optional scopes
)

# Create and send a push notification
push = ua.Push(client)
push.audience = ua.all_
push.notification = ua.notification(alert='Hello, world!')
push.device_types = ua.device_types('ios', 'android')
push.send()

EU Data Center Support

All client classes support the EU data center through the location parameter:

# For EU data center
eu_airship = ua.client.BasicAuthClient(
    key='<app key>',
    secret='<master secret>',
    location='eu'
)