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 or jwtAuthHeader, 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, with credentials from [[ballerina.auth.users]] in Config.toml. Defaults to true so enabling the management API without auth is caught at startup rather than silently exposing an endpoint.

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

Name of the HTTP header that carries the JWT. Defaults to the standard Authorization header, where the token is expected as Bearer <token>. Set it (e.g. X-JWT-Assertion) when a gateway in front of the runtime keeps Authorization for its own credential and forwards the caller's JWT in another header; that header may carry the bare token or Bearer <token>. Header names are case-insensitive. Add a custom header to corsAllowHeaders for browser clients.

With a custom header, the gateway interceptor validates that JWT and, when enableBasicAuth = true, basic auth as well, so the two remain alternatives: a request passes with either credential, and a presented credential that fails is refused. OAuth2 stays on Authorization through @http:ServiceConfig, so with enableOAuth = true every request must also carry an OAuth2 token there.

Expected issuer (iss) claim value for JWT validation. Optional: when unset or blank, the iss claim is not checked.

Expected audience (aud) claim value for JWT validation. Optional: when unset or blank, the aud claim is not checked.

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.