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.
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 tokenprints 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/nodesThe 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 > fileleaves the file empty whenever it fails.
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:
- Get Keycloak Token: Make a POST request to the Keycloak endpoint with a
client_idand user credentials to receive an initial access token. - 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_USERNAMEandFUZZBALL_PASSWORD. If you are following along with the examples, make sure these are set in your execution environment.
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)
The script is structured into configuration constants, two primary functions for authentication, and a main execution block to tie them together.
Configuration Constants: Update the constants at the top of the script (
AUTH_DOMAIN,API_DOMAIN, etc.) to match your specific Fuzzball environment.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.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.SDK Initialization: Once the final
fb_tokenis 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.