PUBLIC ALPHABiztraak is now in public alpha. Share feedback
Biztraak
API Docs
Getting Started Authentication Authorization GraphQL REST API API Errors Compliance API Error Codes Swagger/OpenAPI and REST API Operations Virtual Machine API

API Authentication

All access to the Biztraak API requires authentication.
Biztraak uses OAuth 2.0 / OpenID Connect-compatible bearer tokens for API calls. Enterprise identity federation can use the configured FoxIDs/OIDC or SAML integration. The exact issuer, client registration, and grant availability depend on the environment.

Token types

  • Access Tokens (JWTs): used to authenticate API requests.
  • Refresh Tokens: supported by the platform token server for clients that are registered for refresh tokens and request the required offline access scope.
  • API Tokens: generated manually from the Biztraak dashboard under Profile → API Tokens.

How authentication works

  1. Log In

    • Users authenticate through Biztraak’s identity provider
    • OAuth 2.0 authorization-code flow is supported for configured applications.

  2. Get a Token

    • From the dashboard, generate an API token for scripting/automation.
    • From an enabled OAuth flow → request an access token using the grant and client registration assigned to your application.

  3. Use the Token

    • Include the token in every API call:
Authorization: Bearer <your-token>
  1. Refresh (if needed)
    • Use a refresh token or regenerate via the dashboard.

Example: fetching a token

Use the token endpoint and grant documented for your configured identity client. A client-credentials request has this general shape when that grant is enabled:

curl -X POST https://<issuer>/connect/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 --data-urlencode "grant_type=client_credentials" \
 --data-urlencode "client_id=<client-id>" \
 --data-urlencode "client_secret@client-secret.txt" \
 --data-urlencode "scope=api"

Store the client secret alone in client-secret.txt, with permissions limited to the account running the request:

<client-secret>

Keep the file protected. Never place the client secret directly in a shell command, shell history, or process arguments. A secret manager can provide the same values without storing them in a working file.

Response:

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 "expires_in": 3600,
 "token_type": "Bearer"
}

Token structure

Access tokens are JWTs in the current platform configuration. Claims can vary by issuer and client registration. Do not assume every token contains every optional claim.

  • sub → subject (user ID or service account)
  • exp → expiration time
  • iat → issued at
  • scope → API scopes granted, when issued by the configured client
  • roles → RBAC roles, when included by the configured identity provider

Main API and Compliance.Api contracts

The main web API accepts bearer access tokens issued by the canonical identity issuer configured for your environment. Send the token in the Authorization: Bearer <token> header.

Compliance.Api is a separate resource server. It validates its configured issuer and signing keys, then requires the token to include a team_id or tenant_id claim whose GUID matches that deployment's configured TenantOptions.TeamId. A token accepted by the main web API, including the current frontend bearer-token flow, is not established as authorized for Compliance.Api unless it also satisfies that tenant-claim requirement.

Best practices

  • Store tokens securely (env vars, secret managers)
  • Rotate tokens regularly
  • Use service accounts for automation, not personal accounts
  • Audit token usage via Audit Logs

Next steps