servicepytan.auth module

Authenticating with ServiceTitan API

class servicepytan.auth.ApiEnvironment(value)[source]

Bases: StrEnum

Enumeration for ServiceTitan API environments.

This enum defines the available API environments for ServiceTitan, allowing users to switch between production and integration environments.

PRODUCTION: Production environment for live data

INTEGRATION: Integration environment for testing

PRODUCTION = 'production'

INTEGRATION = 'integration'

servicepytan.auth.get_auth_root_url(env='production')[source]

Get the authentication root URL for the specified environment.

Parameters:: env (str) – The API environment (production or integration)
Returns:: The authentication root URL for the specified environment
Return type:: str
Raises:: ValueError – If the environment is not recognized

Examples

>>> get_auth_root_url(ApiEnvironment.PRODUCTION)
'https://auth.servicetitan.io'
>>> get_auth_root_url(ApiEnvironment.INTEGRATION)
'https://auth-integration.servicetitan.io'

servicepytan.auth.get_api_root_url(env='production')[source]

Get the API root URL for the specified environment.

Parameters:: env (str) – The API environment (production or integration)
Returns:: The API root URL for the specified environment
Return type:: str
Raises:: ValueError – If the environment is not recognized

Examples

>>> get_api_root_url(ApiEnvironment.PRODUCTION)
'https://api.servicetitan.io'
>>> get_api_root_url(ApiEnvironment.INTEGRATION)
'https://api-integration.servicetitan.io'

servicepytan.auth.servicepytan_connect(api_environment=ApiEnvironment.PRODUCTION, app_key=None, tenant_id=None, client_id=None, client_secret=None, app_id=None, timezone='UTC', config_file=None)[source]

Establish connection configuration for ServiceTitan API.

This function creates a configuration object with all necessary credentials and settings for connecting to the ServiceTitan API. It can source credentials from function parameters, a config file, or environment variables.

Parameters:

api_environment (str) – The API environment to use (production or integration)
app_key (str) – ServiceTitan application key
tenant_id (str) – ServiceTitan tenant identifier
client_id (str) – OAuth client ID for authentication
client_secret (str) – OAuth client secret for authentication
app_id (str) – ServiceTitan application ID (optional)
timezone (str) – Timezone for date operations (defaults to “UTC”)
config_file (str) – Path to JSON configuration file containing credentials

Returns:

Configuration object containing all necessary authentication settings

Return type:

dict

Examples

>>> # Using parameters
>>> conn = servicepytan_connect(
...     api_environment="production",
...     app_key="your_app_key",
...     tenant_id="your_tenant_id",
...     client_id="your_client_id",
...     client_secret="your_client_secret"
... )

>>> # Using config file
>>> conn = servicepytan_connect(config_file="credentials.json")

>>> # Using environment variables (will auto-load from .env)
>>> conn = servicepytan_connect()

servicepytan.auth.request_auth_token(auth_root_url, client_id, client_secret)[source]

Fetches Auth Token.

Retrieves authentication token for completing a request against the API

Parameters:

client_id – String, provided from the integration settings
client_secret – String, provided from the integration settings

Returns:

Authentication token

Raises:

TBD –

servicepytan.auth.get_auth_token(conn)[source]

Fetches Auth Token using the connection configuration.

Retrieves the CLIENT_ID and CLIENT_SECRET entries from the connection object and requests an authentication token from the ServiceTitan API.

Parameters:: conn – Dictionary containing the credential configuration
Returns:: Authentication token
Return type:: str
Raises:: requests.HTTPError – If the authentication request fails

servicepytan.auth.get_app_key(conn)[source]

Fetches App Key from the connection configuration.

Retrieves the APP_KEY entry from the connection object.

Parameters:: conn – Dictionary containing the credential configuration
Returns:: ServiceTitan App Key
Return type:: str
Raises:: KeyError – If the APP_KEY is not found in the connection configuration

servicepytan.auth.get_tenant_id(conn)[source]

Fetches Tenant ID from the connection configuration.

Retrieves the TENANT_ID entry from the connection object.

Parameters:: conn – Dictionary containing the credential configuration
Returns:: ServiceTitan Tenant ID
Return type:: str
Raises:: KeyError – If the TENANT_ID is not found in the connection configuration

servicepytan.auth.get_auth_headers(conn)[source]

Generates the Authentication Headers for each API request.

Creates a dictionary that includes the auth token and app key formatted to create the authentication headers required by the ServiceTitan API.

Parameters:

conn – Dictionary containing the credential configuration

Returns:

Dictionary containing Authorization and ST-App-Key headers

Return type:

dict

Raises:

requests.HTTPError – If authentication token retrieval fails
KeyError – If required credentials are missing

Examples

>>> headers = get_auth_headers(conn)
>>> # headers = {
>>> #     "Authorization": "Bearer your_token_here",
>>> #     "ST-App-Key": "your_app_key_here"
>>> # }