ballerina/workflow.management.rest Ballerina library

Claim holding the caller's user ID in token mode. Dotted paths address nested claims. Common values: sub (default), preferred_username, email.

Claim holding the caller's roles in token mode. Dotted paths address nested claims — e.g. realm_access.roles for Keycloak, roles or groups for Entra ID. The claim value may be an array of strings or a comma-separated string.

When true, x-user-id / x-user-roles headers sent by the client take precedence over token claims — for topologies where a trusted gateway terminates OAuth and forwards identity headers. Leave false (the default) so a valid token's claims always win and headers cannot spoof identity.

Enforces OAuth scopes per operation class in token mode. Requires JWT or OAuth2 auth to be enabled. Scopes are read from the scope claim (space-delimited, RFC 6749) or the scp claim (array or string).

Scope permitting read operations on workflows (list, get, history, graphs).

Scope permitting workflow mutations (start, suspend, resume, terminate, cancel). Implies scopeWorkflowView for the workflow routes.

Scope permitting read operations on human tasks.

Scope permitting human-task mutations (complete, fail). Implies scopeHumanTaskView for the human-task routes.

Master switch for the management HTTP API. When false (the default), no listener is created and the port is not reserved — importing this module purely for its programmatic helpers opens no port. Workflow execution runs independently of this flag. Set to true in Config.toml to activate the API.

TCP port the management service listens on. Default is 8234.

Enables HTTPS on the listener. Suitable for external deployments; leave false for K8s-internal services where TLS termination is handled by the ingress controller. When true, both certFile and keyFile must be non-empty or the program panics at startup with a descriptive error.

Path to the PEM-encoded TLS certificate file. Required when enableTls = true.

Path to the PEM-encoded TLS private key file. Required when enableTls = true.

Enables CORS headers on the listener. Set to false if CORS is handled upstream (e.g. by an API gateway).

Allowed CORS origins. Defaults to ["*"] (allow all origins). Restrict to specific origins in production, e.g. ["https://portal.example.com"].

Allowed HTTP methods for CORS requests. Defaults to all standard REST methods.

Allowed request headers for CORS requests. Defaults to common headers used by the management API. If you customize apiKeyHeader, ensure it's included in this list.

Whether to allow credentials (cookies, authorization headers) in CORS requests. Set to true if your frontend needs to send credentials.

Maximum age (in seconds) for caching CORS preflight responses. Defaults to ~24 hours (84900 seconds).

Enables HTTP Basic Authentication via Ballerina's built-in file user store. Defaults to true so that accidentally enabling the management API without any auth is caught at startup rather than silently exposing an endpoint. Set to false for K8s-internal deployments (zero-trust / service mesh).

When true, user credentials must be configured in Config.toml using the standard Ballerina user store format:

[[ballerina.auth.users]]
username = "admin"
password = "workflowadmin"
scopes   = ["admin"]

Authentication is delegated to Ballerina HTTP's fileUserStoreConfig handler, which implements the standard HTTP Basic scheme including proper challenge headers and error responses.

Enables JWT Bearer token authentication (Authorization: Bearer <token>). Tokens are validated against the JWKS endpoint specified by jwksUrl. When true, jwtIssuer, jwtAudience, and jwksUrl must all be non-empty or the program panics at startup.

Expected issuer (iss) claim value for JWT validation. Required when enableJwtAuth = true.

Expected audience (aud) claim value for JWT validation. Required when enableJwtAuth = true.

JWKS endpoint URL used to fetch public keys for JWT signature verification. Required when enableJwtAuth = true.

Enables OAuth2 Bearer token authentication via token introspection. When true, oauth2IntrospectionUrl must be non-empty or the program panics at startup.

OAuth2 token introspection endpoint URL. Required when enableOAuth = true.

Enables API key authentication via a custom request header. When true, apiKeyValue must be non-empty or the program panics at startup.

Name of the HTTP header that carries the API key. Defaults to x-api-key.

Expected API key value. Required when enableApiKey = true.