API docs by Redocly

Workflow Approval System API (0.0.9)

Download OpenAPI specification:

API for a SaaS platform that allows customers to manage approvals for generic workflows, users, and groups.

Authentication

OIDC authentication and token management

Initiate OIDC login

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

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Handle OIDC callback

Handles the callback from OIDC provider and redirects to success page with authorization code

query Parameters
code
required
string

Authorization code from OIDC provider

state
required
string

State parameter to prevent CSRF attacks

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Exchange authorization code for JWT token

Exchanges the authorization code and state for a JWT token containing user information and roles

Request Body schema: application/json
required
code
required
string

Authorization code received from OIDC provider

state
required
string

State parameter used for CSRF protection

Responses

Request samples

Content type
application/json
{
  • "code": "auth_code_123",
  • "state": "state_123"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Authentication success page

Returns success message for completed authentication

Responses

Response samples

Content type
application/json
{
  • "message": "Authentication successful. Use the code and state to generate a JWT token."
}

Authentication error page

Returns error message for failed authentication

Responses

Response samples

Content type
application/json
{
  • "message": "Authentication successful. Use the code and state to generate a JWT token."
}

Get authenticated entity information

Returns basic information about the authenticated entity

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "entityType": "user"
}

Workflows

Workflow management and approval

Create a new workflow

Creates a new workflow with approvers and rules

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

User-friendly name for the workflow

description
string

Detailed description of the workflow

metadata
object

Additional custom metadata for the workflow

workflowTemplateId
required
string <uuid>

The unique identifier of the workflow template to use as parent

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "metadata": { },
  • "workflowTemplateId": "53e62d87-459b-4f1f-ae45-ffe2549e140f"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

List workflows

Returns a list of workflows with optional filtering

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

include
Array of strings
Items Value: "workflow-template"

Comma-separated list of related objects to include in the response

include-only-non-terminal-state
boolean
Default: false

When set to true, only workflows that are not in terminal state will be returned. Terminal states are: APPROVED, CANCELED, EXPIRED. Non-terminal state: EVALUATION_IN_PROGRESS.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get workflow details

Returns the details of a specific workflow

Authorizations:
bearerAuth
path Parameters
workflowId
required
string

The unique identifier of the workflow

query Parameters
include
Array of strings
Items Value: "workflow-template"

Comma-separated list of related objects to include in the response

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "workflowTemplateId": "53e62d87-459b-4f1f-ae45-ffe2549e140f",
  • "metadata": { },
  • "ref": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2025-04-15T12:05:00Z"
}

Workflow Templates

Workflow template management

Create a new workflow template

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

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

User-friendly name for the workflow template

description
string

Detailed description of the workflow template

metadata
object

Additional custom metadata for the workflow template

required
any (ApprovalRule)

Configuration of approval rules. Can be a boolean operator (AND/OR) combining nested rules, or a specific requirement (minimum count from a group).

Array of any (WorkflowAction)

Actions to be executed when workflow is approved

defaultExpiresInHours
integer [ 1 .. 8760 ]

Default expiry time for workflows created from this template (in hours, max 1 year)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "metadata": { },
  • "approvalRule": {
    },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "version": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "allowVotingOnDeprecatedTemplate": true,
  • "approvalRule": {
    },
  • "metadata": { },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List workflow templates

Returns a list of workflow templates with optional filtering

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get workflow template details

Returns the details of a specific workflow template

Authorizations:
bearerAuth
path Parameters
templateId
required
string

The unique identifier of the workflow template

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "version": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "allowVotingOnDeprecatedTemplate": true,
  • "approvalRule": {
    },
  • "metadata": { },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a workflow template

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

Authorizations:
bearerAuth
path Parameters
templateName
required
string

The name of the workflow template to update

Request Body schema: application/json
required
description
string

Detailed description of the workflow template

metadata
object

Additional custom metadata for the workflow template

any (ApprovalRule)

Configuration of approval rules. Can be a boolean operator (AND/OR) combining nested rules, or a specific requirement (minimum count from a group).

Array of any (WorkflowAction)

Actions to be executed when workflow is approved

defaultExpiresInHours
integer [ 1 .. 8760 ]

Default expiry time for workflows created from this template (in hours, max 1 year)

cancelWorkflows
boolean
Default: false

If true, all in-progress workflows associated with this template will be canceled when creating a new version. This affects the allowVotingOnDeprecatedTemplate setting: when true, voting is disabled on the deprecated template.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "metadata": { },
  • "approvalRule": {
    },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1,
  • "cancelWorkflows": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "version": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "allowVotingOnDeprecatedTemplate": true,
  • "approvalRule": {
    },
  • "metadata": { },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Deprecate a workflow template

Marks a workflow template as deprecated with optional workflow cancellation

Authorizations:
bearerAuth
path Parameters
templateName
required
string

The name of the workflow template to deprecate

Request Body schema: application/json
optional

Options for deprecating a workflow template.

cancelWorkflows
boolean
Default: false

If true, all in-progress workflows associated with this template will be canceled. This affects the allowVotingOnDeprecatedTemplate setting: when true, voting is disabled on the deprecated template.

Responses

Request samples

Content type
application/json
{
  • "cancelWorkflows": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "version": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "allowVotingOnDeprecatedTemplate": true,
  • "approvalRule": {
    },
  • "metadata": { },
  • "actions": [
    ],
  • "defaultExpiresInHours": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Users

User management

Create a new user

Creates a new user in the system.

Authorizations:
bearerAuth
Request Body schema: application/json
required
displayName
required
string

User's display name.

email
required
string <email>

User's email address (must be unique).

orgRole
required
string

Role assigned to the user within the organization.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Alex Chen",
  • "email": "alex.chen@example.com",
  • "orgRole": "member"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

List users

Returns a list of users

Authorizations:
bearerAuth
query Parameters
search
string

Fuzzy search term for user display name or email.

page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pagination": {
    }
}

Get user details

Returns the details of a specific user by their ID.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

The unique identifier (UUID) of the user.

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  • "displayName": "Alex Chen",
  • "email": "alex.chen@example.com",
  • "orgRole": "member",
  • "createdAt": "2025-04-15T12:05:00Z"
}

List entities in a group

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

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "entities": [
    ],
  • "pagination": {
    }
}

Add group entities

Add entities (like users) within a specific group.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

Request Body schema: application/json
required
required
Array of objects (EntityMembershipAdd)

List of entities to add to the group.

Responses

Request samples

Content type
application/json
{
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "entitiesCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Remove group entities

Remove entities (like users) from a specific group.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

Request Body schema: application/json
required
required
Array of objects (EntityMembershipRemove)

List of entities to remove from the group.

Responses

Request samples

Content type
application/json
{
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "entitiesCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Groups

Group management

Create a new approver group

Create a new group for organizing approvers

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the group

description
string

Description of the group

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

List groups

Returns a list of groups

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "pagination": {
    }
}

Get group details

Returns the details of a specific group

Authorizations:
bearerAuth
path Parameters
groupIdentifier
required
string

The unique identifier of the group or the name of the group

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "entitiesCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List entities in a group

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

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "entities": [
    ],
  • "pagination": {
    }
}

Add group entities

Add entities (like users) within a specific group.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

Request Body schema: application/json
required
required
Array of objects (EntityMembershipAdd)

List of entities to add to the group.

Responses

Request samples

Content type
application/json
{
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "entitiesCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Remove group entities

Remove entities (like users) from a specific group.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

The unique identifier (UUID) of the group.

Request Body schema: application/json
required
required
Array of objects (EntityMembershipRemove)

List of entities to remove from the group.

Responses

Request samples

Content type
application/json
{
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "entitiesCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Organization Admins

Organization administrator management

Add organization administrator

Adds a new organization administrator by email to the specified organization

Authorizations:
bearerAuth
path Parameters
organization-name
required
string
Example: my-org

The name or identifier of the organization

Request Body schema: application/json
required
email
required
string <email>

Email address of the organization administrator

Responses

Request samples

Content type
application/json
{
  • "email": "admin@example.com"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

List organization administrators

Returns a list of administrators for the specified organization

Authorizations:
bearerAuth
path Parameters
organization-name
required
string
Example: my-org

The name or identifier of the organization

query Parameters
page
integer
Default: 1

Page number for pagination

limit
integer
Default: 20

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Remove organization administrator

Removes an organization administrator from the specified organization

Authorizations:
bearerAuth
path Parameters
organization-name
required
string
Example: my-org

The name or identifier of the organization

Request Body schema: application/json
required
userId
required
string <uuid>

The unique identifier of the user to remove from organization admins

Responses

Request samples

Content type
application/json
{
  • "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Workflow Actions

Workflow actions and voting

Vote on a workflow

Allows an authenticated entity to cast a vote (approve or veto) on a specific workflow.

Authorizations:
bearerAuth
path Parameters
workflowId
required
string

The unique identifier of the workflow

Request Body schema: application/json
required
reason
string

Optional reason for the vote. Can be used for approval comments or reject reasons.

required
any

Responses

Request samples

Content type
application/json
{
  • "reason": "Missing critical information or LGTM!",
  • "voteType": {
    }
}

Response samples

Content type
application/json
{ }

Check if the current entity can vote on a workflow

Determines if the authenticated entity is eligible to cast a vote on the specified workflow.

Authorizations:
bearerAuth
path Parameters
workflowId
required
string

The unique identifier of the workflow.

Responses

Response samples

Content type
application/json
{
  • "canVote": true,
  • "voteStatus": "VOTE_PENDING",
  • "cantVoteReason": "string"
}