Skip to main content

API Authentication

Witboost Platform APIs require authentication to ensure secure access to platform resources. This page describes the available authentication methods for both service accounts and individual users.

Overview​

All Witboost Platform APIs support authentication through two primary methods:

  1. Bearer Token Authentication (recommended) - Using short-lived JWT tokens
  2. Basic Authentication - Using an access token directly

Both methods rely on an access token, which can be one of:

  • Service account access token — for automated or programmatic access. Requires a service account to be created by a platform administrator. See the Service Accounts documentation.
  • Personal Access Token (PAT) — for individual user access (e.g., using the Witboost CLI or calling APIs on behalf of a user). Each user can generate their own PAT from their profile settings. See Personal Access Tokens.

Prerequisites​

Before authenticating with Witboost APIs, you need an active access token. Depending on your use case:

Service Account Access Token​

Use this for automated or programmatic access (e.g., CI/CD pipelines, backend integrations):

  1. Navigate to Administration Panel → IAM → Service Accounts
  2. Create a new service account with appropriate permissions
  3. Generate an access token for the service account
tip

Only users with the platform.users.service-accounts.edit permission can create service accounts, and only users with the platform.users.service-accounts.access-tokens.edit permission can generate access tokens.

Personal Access Token (PAT)​

Use this for individual user access (e.g., using the Witboost CLI or calling APIs as yourself):

  1. Click on your profile picture to access the Settings and Profile page
  2. Go to the Advanced tab
  3. Generate an access token
info
  • Each account can have only one active PAT at a time.
  • Tokens can optionally have an expiration date.
  • The token is only visible at the time of creation — copy and store it securely.
  • You can revoke a token to invalidate it, or regenerate one to replace it while keeping the same expiration date.

For full details, see Personal Access Tokens.

Authentication Methods​

Bearer token authentication uses short-lived JWT tokens that are exchanged from your access token. This is the recommended method for production use as it provides better security through token rotation and scoping.

Obtaining a JWT Token​

Exchange your access token for a JWT by calling the JWT exchange endpoint.

Basic example:

curl -X POST https://your-witboost-instance.com/api/auth/access-tokens/jwt \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "wbat-YOUR-ACCESS-TOKEN",
    "duration_seconds": 3600,
    "scope": "service:computational-governance"
  }'
tip

For complete API details, parameters, and response formats, see the Platform Admin API documentation.

Using the JWT Token​

Include the JWT in the Authorization header of your API requests:

curl https://your-witboost-instance.com/api/catalog/entities \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Python example:

import requests

# Get JWT token
token_response = requests.post(
    'https://your-witboost-instance.com/api/auth/access-tokens/jwt',
    json={
        'access_token': 'wbat-YOUR-ACCESS-TOKEN',
        'duration_seconds': 3600
    }
)
jwt_token = token_response.json()['jwt']

# Use JWT to call API
response = requests.get(
    'https://your-witboost-instance.com/api/catalog/entities',
    headers={'Authorization': f'Bearer {jwt_token}'}
)

print(response.json())

Token Lifecycle​

  • Duration: JWTs are valid for the specified duration (default 5 minutes, configurable)
  • Rotation: Generate a new JWT before the current one expires
  • Invalidation: Revoking the access token does not immediately invalidate active JWTs created from it
  • Scope: JWTs can be scoped to specific services for enhanced security. e.g. Computational Governance
info

For complete information on token parameters and constraints, refer to the JWT exchange API documentation.

Basic Authentication​

Basic Authentication provides a simpler alternative using your service account access token directly. The platform automatically converts the Basic Auth credentials into a short-lived JWT.

Enabling Basic Authentication​

Basic Authentication is by default disabled and must be enabled in your values.yaml of your Witboost installation as follows:

# inside your values.yaml
ui:
  appConfig:
    # ... other configurations  ...
    backend:
      auth:
        basicAuth:
          enabled: true

governance-platform:
  configOverride: |-
    # ... other configurations ...
    computational-governance-platform {
      # ... other properties ...
      platform-services = {
        auth = {
          basic-auth = {
            enabled = true
          }
        }
    }

Basic authentication is only available for the UI and Computational Governance modules, as they are the only services which are intended to be reached by end users and applications via APIs.

Header Format​

Authorization: Basic base64("witboost:<your access token>")

The username must be exactly witboost. The password is your service account access token (e.g., wbat-...).

Usage Examples​

curl:

curl -u "witboost:wbat-YOUR-ACCESS-TOKEN" \
  https://your-witboost-instance.com/api/catalog/entities \
  -H "Content-Type: application/json"

Python example:

import requests

# Using auth parameter (recommended)
response = requests.get(
    'https://your-witboost-instance.com/api/catalog/entities',
    auth=('witboost', 'wbat-YOUR-ACCESS-TOKEN')
)

print(response.json())

Token Management​

  1. Never commit tokens to version control - Use environment variables or secret management tools (AWS Secrets Manager, HashiCorp Vault, etc.)

  2. Use HTTPS in production - Always use secure connections to prevent credentials from being transmitted in clear text

  3. Rotate access tokens regularly - Generate new tokens periodically and revoke old tokens when no longer needed

  4. Use minimal token durations - For Bearer tokens, request only the duration needed to reduce the impact of token compromise

Service-Specific Requirements​

Computational Governance API​

The Computational Governance API supports both authentication methods:

  • Bearer Token: Requires the service:computational-governance scope when exchanging the access token for a JWT
  • Basic Authentication: Fully supported

Example with Bearer Token:

curl -X POST https://your-witboost-instance.com/api/auth/access-tokens/jwt \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "wbat-YOUR-ACCESS-TOKEN",
    "duration_seconds": 3600,
    "scope": "service:computational-governance"
  }'

Example with Basic Auth:

curl -u "witboost:wbat-YOUR-ACCESS-TOKEN" \
  https://your-witboost-instance.com/api/computational-governance/validate \
  -H "Content-Type: application/json" \
  -d '{"policy": "..."}'

For more information, see Computational Governance Authentication.