Authentication

The pd4castr Python SDK uses OAuth 2.0 Client Credentials to authenticate with the API. This is a machine-to-machine (M2M) flow designed for automated scripts, pipelines, and backend integrations — it doesn’t require interactive login.

How it works

The Client Credentials flow exchanges a client_id and client_secret pair for a short-lived access token:

1. On your first API call, the SDK sends your credentials to Auth0’s /oauth/token endpoint.
2. Auth0 returns an access token and an expiry time.
3. The SDK caches the token in memory and attaches it to every subsequent request.
4. When the token is within 10 seconds of expiry, the SDK automatically fetches a new one on the next API call.

You don’t need to manage tokens manually. The SDK handles the entire lifecycle transparently.

Obtaining credentials

Your client_id and client_secret are issued per organisation. These are separate from the interactive login used by the CLI and web app.

To request credentials, contact your organisation admin or the pd4castr team. They will provision a set of M2M credentials for your organisation.

Passing credentials to the client

Provide your credentials when you create a Client instance:

from pd4castr_api_sdk import Client
 
client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

Security best practices

Never hardcode credentials in your source code. Instead, use environment variables or a secrets manager.

Here’s how to load credentials from environment variables:

import os
from pd4castr_api_sdk import Client
 
client = Client(
    client_id=os.environ["PD4CASTR_CLIENT_ID"],
    client_secret=os.environ["PD4CASTR_CLIENT_SECRET"],
)

Other recommendations:

• Store credentials in a .env file (and add it to .gitignore) or use your platform’s secrets management (for example, GitHub Actions secrets, AWS Secrets Manager, or Vault).
• Rotate credentials periodically and revoke any that are compromised.
• Limit credential access to the services and team members that need them.

Advanced configuration

The Client constructor accepts optional parameters to override the default Auth0 and API endpoints. This is useful for staging environments or self-hosted deployments.

client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
    base_url="https://api.staging.pd4castr.com.au",
    auth0_domain="staging.au.auth0.com",
    auth0_audience="https://api.staging.pd4castr.com.au",
    timeout=60.0,
)

Resolution order

The SDK resolves configuration values in this order:

1. Constructor arguments (highest priority)
2. Environment variables (PD4CASTR_API_URL, PD4CASTR_AUTH0_DOMAIN, PD4CASTR_AUTH0_AUDIENCE)
3. Built-in defaults (lowest priority)

Authentication errors

If your credentials are invalid or expired, the SDK raises an AuthenticationError:

from pd4castr_api_sdk import Client
 
try:
    client = Client(
        client_id="invalid-id",
        client_secret="invalid-secret",
    )
    client.get_models()
except Exception as e:
    print(f"Authentication failed: {e}")

Verify that your client_id and client_secret are correct and that your organisation’s M2M credentials are still active.

Next steps

• Quick start — get up and running with your first API call
• Reference — full Client constructor details and all available methods