Workflow Approval System API (0.0.29)

Initiates OIDC authentication by generating PKCE challenge and redirecting to the OIDC provider

Initiates OIDC authentication specifying a loopback redirect URI for the CLI

Exchanges authorization code for tokens and sets them as HttpOnly cookies, then redirects to frontend

Takes the refresh_token from the HttpOnly cookie and issues a new pair of tokens as cookies

Initiates step-up authentication flow returning the authorization URL as JSON.

Exchanges an IDP token for a high-privilege step-up token and sets it as an HttpOnly cookie.

Initiates the step-up authentication flow for the CLI by redirecting to the IDP. The CLI should open the returned redirect URL in a browser. After the user authenticates, the IDP will redirect to the CLI local server with a code and state parameter, which must then be exchanged via POST /auth/cli/exchangePrivilegedToken.

Exchanges an IDP authorization code for a high-privilege step-up token, returned as JSON.

Exchanges an IDP authorization code and state for a pair of access and refresh tokens, returned as JSON.

Exchanges a refresh token for a new pair of access and refresh tokens, returned as JSON.

Returns basic information about the authenticated entity

Creates an encrypted challenge that must be signed by the agent to obtain a token.

Challenge Format (Server → Agent): The server generates a challenge encrypted with the agent's public key. When decrypted and base64 decoded, it contains a JSON object with:

• audience: string (agent name)
• expires_at: ISO 8601 formatted date-time string
• issuer: string (the name of the SaaS platform, e.g., "Approvio")
• nonce: a random string to ensure uniqueness (the actual challenge)

Validates a JWT assertion and returns a JWT access token for the authenticated agent using OAuth 2.0 JWT Bearer profile (RFC 7523).

JWT Assertion Requirements: The agent must create and sign a JWT assertion with their private key containing:

• iss (issuer): Agent name
• sub (subject): Agent name (same as issuer for client authentication)
• aud (audience): Authorization server identifier
• exp (expiration): JWT expiration time (Unix timestamp)
• jti (JWT ID): Unique nonce from the server's challenge (prevents replay attacks)
• iat (issued at): JWT issued time (Unix timestamp, optional)

Security Notes:

• JWT must be signed with RS256 algorithm using the agent's private key
• Server verifies signature using agent's registered public key
• Each challenge nonce can only be used once (replay protection)
• Agent identity is extracted from the JWT issuer claim

Exchanges a refresh token for a new pair of access and refresh tokens. Requires DPoP proof.

Creates a new workflow with approvers and rules

Returns a list of workflows with optional filtering

Returns the details of a specific workflow

Creates a new workflow template with approval rules, actions, and default expiry settings

Returns a list of workflow templates with optional filtering

Returns the details of a specific workflow template.

Updates an existing workflow template by creating a new version and optionally canceling active workflows

Marks a workflow template as deprecated with optional workflow cancellation

Creates a new user in the system.

Returns a list of users

Returns the details of a specific user by their ID.

Assigns standard roles to a user by replacing all existing role assignments. Roles are specified by their system-defined names and scopes. The user must be authenticated as a human (not an agent) to use this endpoint.

Removes specified roles from a user. Only the roles matching both the role name and scope will be removed. The user must be authenticated as a human (not an agent) to use this endpoint.

Returns a list of all entities (users, systems, etc.) that belong to a specific group, including their roles.

Add entities (like users) within a specific group.

Remove entities (like users) from a specific group.

Create a new group for organizing approvers

Returns a list of groups

Returns the details of a specific group

Returns a list of all entities (users, systems, etc.) that belong to a specific group, including their roles.

Add entities (like users) within a specific group.

Remove entities (like users) from a specific group.

Creates a new organizational space

Returns a list of spaces

Returns the details of a specific space

Deletes a space

Adds a new organization administrator by email to the specified organization