Cybrid Organization API Python Client

Common errors

• cybrid_api_organization.exceptions.ApiException: (401)
  Reason: Unauthorized

  cause The provided Bearer Token is missing, expired, or invalid, leading to failed authentication against the Cybrid API.
  fix Verify that the `CYBRID_BEARER_TOKEN` environment variable is correctly set and contains a current, valid token. Re-generate the token if necessary from the Cybrid Sandbox dashboard or Identity API. Ensure proper refresh mechanisms if tokens have a short expiry.

• ModuleNotFoundError: No module named 'cybrid_api_organization'

  cause The `cybrid-api-organization-python` package is not installed in the current Python environment, or the import path is incorrect.
  fix Install the package using `pip install cybrid-api-organization-python`. Double-check import statements for typos (e.g., `cybrid_api_organization` vs `cybrid-api-organization-python`).

• cybrid_api_organization.exceptions.ApiException: (403)
  Reason: Forbidden

  cause The authenticated Bearer Token does not possess the required scopes or permissions to perform the requested API operation.
  fix Review the Cybrid API documentation for the specific endpoint to identify the required scopes. Ensure your Bearer Token is generated with these necessary scopes. If performing customer-specific actions, use a customer-scoped token rather than a broader organization or bank token.

Warnings

• breaking Cybrid's API (including v1) can undergo breaking changes. The company aims to provide at least 60 days' notice via their Changelog for such updates. Since this client is auto-generated from OpenAPI specs, API changes directly impact the client library.
  Fix: Regularly monitor the Cybrid Changelog and update your client library and code according to the announced changes. Ensure your CI/CD pipelines can detect and adapt to new client versions.
• gotcha API credentials (Client ID and Secret) should never be hardcoded or stored directly in source code. They are highly sensitive and can lead to security breaches if compromised.
  Fix: Always store Client ID and Secret server-side, preferably in environment variables or a dedicated secrets management tool (e.g., AWS Secrets Manager, HashiCorp Vault, Google Cloud Secret Manager).
• gotcha Raw API error responses from Cybrid may contain sensitive internal identifiers or diagnostic information. Exposing these directly to end-users can be a security risk and degrade user experience.
  Fix: Implement robust error handling that maps Cybrid API error responses to user-friendly messages. Log full error details securely on the server-side, filtering out sensitive data.
• gotcha Incorrect or insufficient OAuth scopes for your bearer token will result in '403 Forbidden' errors, preventing access to specific API endpoints or operations.
  Fix: Ensure that the bearer token used for authentication has the necessary OAuth scopes for the API calls being made. For customer-specific operations, generate customer-scoped access tokens to adhere to the principle of least privilege.

Install

• pip install cybrid-api-organization-python Install latest version

Imports

• Configuration

  from cybrid_api_organization import Configuration

• ApiClient

  from cybrid_api_organization import ApiClient

• OrganizationsApi

  from cybrid_api_organization.api.organizations_api import OrganizationsApi

• ApiException
  wrong:

  from cybrid_api_organization.rest import ApiException

  correct:

  from cybrid_api_organization.exceptions import ApiException

  Exceptions are typically in the 'exceptions' submodule, not 'rest' in newer OpenAPI generators.

Quickstart

This quickstart demonstrates how to configure the Cybrid Organization API client, authenticate using an OAuth 2.0 Bearer Token, and fetch the current organization's details. It's crucial to obtain the `CYBRID_BEARER_TOKEN` securely, typically from the Cybrid Sandbox dashboard or Identity Provider, and store it as an environment variable or via a secrets manager.

import os
from cybrid_api_organization import Configuration, ApiClient
from cybrid_api_organization.api.organizations_api import OrganizationsApi
from cybrid_api_organization.exceptions import ApiException

# --- Configuration ---
# Authenticate using an Organization Bearer Token generated from the Cybrid Sandbox or Identity API.
# Never hardcode credentials in your source code.
# Get your Bearer Token (e.g., via OAuth Client Credentials Grant Flow) from Cybrid Identity Provider.
# Example: CYBRID_BEARER_TOKEN = os.environ.get('CYBRID_BEARER_TOKEN', 'YOUR_CYBRID_BEARER_TOKEN')

configuration = Configuration(
    host = os.environ.get('CYBRID_ORGANIZATION_API_URL', 'https://organization.sandbox.cybrid.app/api')
)

# The bearer token should be obtained securely (e.g., from an environment variable or secrets manager).
# This example assumes a pre-fetched bearer token.
BEARER_TOKEN = os.environ.get('CYBRID_BEARER_TOKEN', '') # Replace with actual token retrieval method

if not BEARER_TOKEN:
    print("WARNING: CYBRID_BEARER_TOKEN environment variable not set. API calls may fail.")

configuration.access_token = BEARER_TOKEN

# Create an API client configuration
with ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = OrganizationsApi(api_client)

    try:
        # Get Organization details
        # The API often implicitly knows the organization from the bearer token.
        # Some endpoints might require a 'guid' if managing multiple organizations
        # or if the token is not organization-scoped.
        organization = api_instance.get_organization()
        print("Successfully fetched Organization details:")
        print(f"Name: {organization.name}")
        print(f"GUID: {organization.guid}")
        print(f"Created At: {organization.created_at}")

    except ApiException as e:
        print(f"Exception when calling OrganizationsApi->get_organization: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")