Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Authentication

The Fuzzball client SDK calls the Fuzzball API with a valid Fuzzball API token. Obtain that token in one of two ways: read it from the configuration file the Fuzzball CLI writes, or run the whole authentication flow in your own code without a pre-existing configuration file.

Both methods are described below.

Using the CLI Configuration

This method suits local development and interactive sessions, where the Fuzzball CLI is already installed and logged in. The SDK reads the API token straight out of ~/.config/fuzzball/config.yaml.

That is the same initialization every coding example on this site starts from, so it is documented once, with the code, in Initializing the Fuzzball Workflow Service API.

fuzzball context token prints the active context’s token on its own line, so anything outside the SDK that needs a bearer header can read it without parsing the configuration file:

$ curl -H "Authorization: Bearer $(fuzzball context token)" \
    https://api.example.com/v4/nodes

The token is a credential: prefer piping it into the command that needs it over writing it to a file. A token the context knows has expired is reported as an error rather than printed – though only OIDC logins record an expiry; local and service-account logins do not. If you do write a file, write a temporary one and rename it: the shell empties a redirect target before the command runs, so fuzzball context token > file leaves the file empty whenever it fails.

Programmatic Authentication

This method is ideal for non-interactive environments like CI/CD pipelines, automated scripts, or applications where the Fuzzball CLI is not available or a user cannot log in manually. It performs the full authentication flow from directly within your code.

To achieve this, a HTTP client library like requests will be necessary. If you prefer using another http library like httpx or aiohttp, you can replace the http request code accordingly.

The path segment accounts in the token endpoint is the legacy spelling of group; the account_id is the UUID of the Fuzzball group whose token you want.

The authentication flow has two stages:

  1. Get Keycloak Token: Make a POST request to the Keycloak endpoint with a client_id and user credentials to receive an initial access token.
  2. Get Fuzzball Token: Use that access token to make an authorized GET request to the Fuzzball API, exchanging it for the final, Fuzzball-scoped API token.

The example below puts the authentication flow in two functions, get_keycloak_token and get_fuzzball_token, one per stage. Refer to the function docstrings for additional details about their implementation.

Security Best Practice

For security, avoid hardcoding credentials in your scripts. The following example reads the username and password from environment variables called FUZZBALL_USERNAME and FUZZBALL_PASSWORD. If you are following along with the examples, make sure these are set in your execution environment.

Complete Example Script

Here is a complete, runnable script that handles the full authentication flow and then uses the SDK to list workflows for the authenticated group.

import fuzzball
import requests
import sys
import os

def get_keycloak_token(auth_domain, realm_id, client_id, username, password):
    """
    Authenticates with Keycloak using the password grant type.
    """
    print("1. Authenticating with Keycloak...")
    token_url = f"https://{auth_domain}/auth/realms/{realm_id}/protocol/openid-connect/token"
    payload = {
        'grant_type': 'password',
        'client_id': client_id,
        'username': username,
        'password': password,
    }
    headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    try:
        response = requests.post(token_url, data=payload, headers=headers)
        response.raise_for_status()
        access_token = response.json()['access_token']
        print("   -> Success: Obtained Keycloak access token.")
        return access_token
    except requests.exceptions.RequestException as e:
        print(f"   -> Error during Keycloak authentication: {e}")
        return None

def get_fuzzball_token(api_domain, account_id, keycloak_token):
    """
    Exchanges a Keycloak access token for a Fuzzball API token.
    """
    print("\n2. Exchanging for a Fuzzball API token...")
    token_url = f"https://{api_domain}/v4/accounts/{account_id}/token"
    headers = {'Authorization': f"Bearer {keycloak_token}"}
    try:
        response = requests.get(token_url, headers=headers)
        response.raise_for_status()
        fuzzball_token = response.json()['token']
        print(f"   -> Success: Obtained Fuzzball API token for account {account_id}.")
        return fuzzball_token
    except requests.exceptions.RequestException as e:
        print(f"   -> Error obtaining Fuzzball API token: {e}")
        return None

# --- Configuration: Update these values for your environment ---
AUTH_DOMAIN = "auth.example.fuzzball.dev"
API_DOMAIN = "api.example.fuzzball.dev"
REALM_ID = "your-realm-id-here"
CLIENT_ID = "fuzzball-cli"
ACCOUNT_ID = "your-account-id-here"
# --- End Configuration ---

# Load credentials from environment variables
USERNAME = os.environ.get("FUZZBALL_USERNAME")
PASSWORD = os.environ.get("FUZZBALL_PASSWORD")

if __name__ == "__main__":
    if not all([USERNAME, PASSWORD]):
        print("Error: Please set the FUZZBALL_USERNAME and FUZZBALL_PASSWORD environment variables.")
        sys.exit(1)

    # Stages 1 & 2: Get the final Fuzzball token
    kc_token = get_keycloak_token(AUTH_DOMAIN, REALM_ID, CLIENT_ID, USERNAME, PASSWORD)
    if not kc_token:
        sys.exit(1) # Exit if Keycloak auth failed

    fb_token = get_fuzzball_token(API_DOMAIN, ACCOUNT_ID, kc_token)
    if not fb_token:
        sys.exit(1) # Exit if Fuzzball token exchange failed

    # Stage 3: Configure and Use the Fuzzball SDK
    print("\n3. Configuring Fuzzball SDK instance...")
    api_config = fuzzball.Configuration()
    api_config.host = f"https://{API_DOMAIN}/v4"

    # Initialize the API client and set the authorization header
    api_client = fuzzball.ApiClient(api_config)
    api_client.set_default_header("Authorization", f"Bearer {fb_token}")
    print("   -> SDK configured successfully.")

    # You can now use any Fuzzball service API, for example, WorkflowServiceApi
    print("\n4. Using the SDK to list workflows...")
    workflow_api = fuzzball.WorkflowServiceApi(api_client)
    try:
        response = workflow_api.list_workflows()
        for workflow in response.workflows:
            print(f"  - ID: {workflow.id}, Status: {workflow.status}")
    except fuzzball.ApiException as e:
        print(f"   -> Error calling Fuzzball API: {e}")
        sys.exit(1)

Code Breakdown

The script is structured into configuration constants, two primary functions for authentication, and a main execution block to tie them together.

  1. Configuration Constants: Update the constants at the top of the script (AUTH_DOMAIN, API_DOMAIN, etc.) to match your specific Fuzzball environment.

  2. get_keycloak_token(): This function handles the first stage of authentication. It sends your username, password, and client ID to the Keycloak server and returns a short-lived access token.

  3. get_fuzzball_token(): This function handles the second stage. It sends the Keycloak token to the Fuzzball API’s token exchange endpoint and returns the final, Fuzzball-scoped token needed for all subsequent API calls.

  4. SDK Initialization: Once the final fb_token is obtained, it is used to configure the Fuzzball SDK:

    # Configure the Fuzzball host
    api_config = fuzzball.Configuration()
    api_config.host = f"https://{API_DOMAIN}/v4"
    # Initialize the API client and set the authorization header
    api_client = fuzzball.ApiClient(api_config)
    api_client.set_default_header("Authorization", f"Bearer {fb_token}")

With the api_client configured, you can now initialize any Fuzzball service API (e.g., fuzzball.WorkflowServiceApi(api_client)) and begin making calls.

If you would rather keep the main script short, move get_keycloak_token and get_fuzzball_token into their own module – fuzzball_auth.py, say – and import them from it. Nothing about the flow changes.

With authentication working, the coding examples put the initialized workflow service API to use.