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. Importing this module serves the API (the default, true); set false to keep the import without opening the port. ballerina/workflow.management alone never opens a port. Workflow execution runs independently of this flag.

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> by default). 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.

Enabled schemes are alternatives: a request passes with any one valid credential, and a presented credential that fails is refused.

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.