Create and act upon role requests

get/workflow-engine/api/v1/requests

Get the request queue for the user.

offsetint

Offset where to start fetching the items

Default
0
limitint

Number of items to return

Default
50
Max
100
filterstring

required

Filter request items - possible values: requests (all the requests the user has made, active, approved or denied), active_requests (requests currently active, waiting to be approved), approvals (all the requests the current user has made a decision or needs to decide), active_approvals (all the requests the current user can make a decision on), all

Responses

Response examples

Successful response, returns an array of workflows, returns an empty array if no workflows defined

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "requester": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      },
      "requested_role": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "name": "string",
        "deleted": true
      },
      "request_justification": "string",
      "grant_type": "string",
      "grant_start": "2017-01-01T15:05:05Z",
      "grant_end": "2017-01-01T15:05:05Z",
      "floating_length": 24,
      "max_floating_duration": 48,
      "max_time_restricted_duration": 15,
      "target_user": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      },
      "target_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "requestor_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "action": "GRANT",
      "created": "2017-01-01T15:05:05Z",
      "updated": "2017-01-01T15:05:05Z",
      "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "name": "An example workflow",
      "status": "WAITING",
      "comment": "A comment",
      "can_bypass_revoke_workflow": true,
      "steps": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "match": "ALL",
          "approvers": [
            {
              "id": "5bf77342-221c-11ee-be56-0242ac120002",
              "role": {
                "id": "5bf77342-221c-11ee-be56-0242ac120002",
                "name": "string",
                "deleted": true
              },
              "decision": "WAITING",
              "user": {
                "id": "5bf77342-221c-11ee-be56-0242ac120002",
                "display_name": "string"
              },
              "decision_time": "2017-01-01T15:05:05Z",
              "comment": "string"
            }
          ]
        }
      ],
      "approver_can_revoke": true,
      "target_role_revoked": true,
      "target_role_revocation_time": "2017-01-01T15:05:05Z",
      "target_role_revoked_by": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      }
    }
  ]
}
post/workflow-engine/api/v1/requests

Add a workflow to the request queue.

idstring

The UUID of the returned object, unique to a access request.

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
requesterobject

The ID & display name of the user making the access request.

idstring
Format
uuid
display_namestring
deletedboolean

It indicates whether a user is present in the system or not.

requested_roleobject

required

The ID and display name of the access requested role. Display name stored for posterity.

idstring

The ID of the requested role.

Format
uuid
namestring
deletedboolean

It indicates whether a role is present in the system or not. Create/Update workflow/request operations doesn't need to pass any value to this attribute. This field is not read during the Write operations.

request_justificationstring

Justification for the access request.

grant_typestring

Is the role granted permanently, or is the grant time restricted, or a floating window. The floating window starts upon initial connection at which time the Role Store converts the floating window to explicit time-restricted window. Can be overriden in decision phase.

grant_startstring

Date & time after which the role is granted to the user. Can be overriden in decision phase.

Format
date-time
Example
"2017-01-01T15:05:05Z"
grant_endstring

Date & time after which the role is removed from the user. Can be overriden in decision phase.

Format
date-time
Example
"2017-01-01T15:05:05Z"
floating_lengthint

Time in hours how long the grant should last after initial connection. Can be overriden in decision phase.

Example
24
max_floating_durationint

Time in hours how long the grant should not exceed after initial connection.

Example
48
max_time_restricted_durationint

Maximum time in days where duration between start-date and end-date of role request must not exceeded this duration.

Example
15
target_userobject

The ID of the user the request is made for.

idstring
Format
uuid
display_namestring
deletedboolean

It indicates whether a user is present in the system or not.

target_rolesarray

A list of roles this workflow targets.

idstring
Format
uuid
namestring
deletedboolean

It indicates whether a role is present in the system or not. Create/Update workflow/request operations doesn't need to pass any value to this attribute. This field is not read during the Write operations.

requestor_rolesarray

The ID and display name of the access requestor roles. Display name stored for posterity.

idstring

The ID of the requestor role.

Format
uuid
namestring
deletedboolean

It indicates whether a role is present in the system or not. Create/Update workflow/request operations doesn't need to pass any value to this attribute. This field is not read during the Write operations.

actionstring

Does the workflow GRANT or REMOVE the user from the role. Workflow engine needs to check that the requested action matches allowed actions defined in the template.

Enum
  • GRANT
  • REMOVE
  • BOTH
createdstring

When the object was created.

Format
date-time
Example
"2017-01-01T15:05:05Z"
updatedstring

When the object was updated.

Format
date-time
Example
"2017-01-01T15:05:05Z"
updated_bystring

ID of the user who updated the object.

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
authorstring

ID of the user who originally authored the object.

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
namestring

Name of the workflow.

Min Length
4
Max Length
4096
Example
"An example workflow"
statusstring

Computed status for the instance of the workflow - based on step statuses.

Default
"WAITING"
Enum
  • WAITING
  • APPROVED
  • DENIED
commentstring

A comment describing the object.

Example
"A comment"
can_bypass_revoke_workflowboolean

A flag used to determine if approvers can bypass the revoke workflow to revoke a role.

Default
false
stepsarray

Array of steps.

idstring
Format
uuid
namestring

required

Access request name.

matchstring

required

All approvers must approve or any approver can approve.

Enum
  • ALL
  • ANY
approversarray

required

Who are the approvers in this step.

approver_can_revokeboolean

A flag used to determine if approvers can revoke a role from target user.

Default
false
target_role_revokedboolean

Is set to true only when the target role has been revoked via the request by one of the approvers.

Default
false
target_role_revocation_timestring

Date and time of revocation.

Format
date-time
Example
"2017-01-01T15:05:05Z"
target_role_revoked_byobject

User object of who revoked the target role.

idstring
Format
uuid
display_namestring
deletedboolean

It indicates whether a role is present in the system or not.

Responses

Request examples

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "requester": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  },
  "requested_role": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "name": "string",
    "deleted": true
  },
  "request_justification": "string",
  "grant_type": "string",
  "grant_start": "2017-01-01T15:05:05Z",
  "grant_end": "2017-01-01T15:05:05Z",
  "floating_length": 24,
  "max_floating_duration": 48,
  "max_time_restricted_duration": 15,
  "target_user": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  },
  "target_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "requestor_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "action": "GRANT",
  "created": "2017-01-01T15:05:05Z",
  "updated": "2017-01-01T15:05:05Z",
  "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "name": "An example workflow",
  "status": "WAITING",
  "comment": "A comment",
  "can_bypass_revoke_workflow": true,
  "steps": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "match": "ALL",
      "approvers": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "role": {
            "id": "5bf77342-221c-11ee-be56-0242ac120002",
            "name": "string",
            "deleted": true
          },
          "decision": "WAITING",
          "user": {
            "id": "5bf77342-221c-11ee-be56-0242ac120002",
            "display_name": "string"
          },
          "decision_time": "2017-01-01T15:05:05Z",
          "comment": "string"
        }
      ]
    }
  ],
  "approver_can_revoke": true,
  "target_role_revoked": true,
  "target_role_revocation_time": "2017-01-01T15:05:05Z",
  "target_role_revoked_by": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  }
}

Response examples

Workflow successfully added to the request queue

{
  "id": "5bf77342-221c-11ee-be56-0242ac120002"
}
get/workflow-engine/api/v1/requests/{request_id}

Gets a request object by ID.

request_idstring

required

Request item ID

Responses

Response examples

Successful response, returns the request item if found

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "requester": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  },
  "requested_role": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "name": "string",
    "deleted": true
  },
  "request_justification": "string",
  "grant_type": "string",
  "grant_start": "2017-01-01T15:05:05Z",
  "grant_end": "2017-01-01T15:05:05Z",
  "floating_length": 24,
  "max_floating_duration": 48,
  "max_time_restricted_duration": 15,
  "target_user": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  },
  "target_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "requestor_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "action": "GRANT",
  "created": "2017-01-01T15:05:05Z",
  "updated": "2017-01-01T15:05:05Z",
  "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "name": "An example workflow",
  "status": "WAITING",
  "comment": "A comment",
  "can_bypass_revoke_workflow": true,
  "steps": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "match": "ALL",
      "approvers": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "role": {
            "id": "5bf77342-221c-11ee-be56-0242ac120002",
            "name": "string",
            "deleted": true
          },
          "decision": "WAITING",
          "user": {
            "id": "5bf77342-221c-11ee-be56-0242ac120002",
            "display_name": "string"
          },
          "decision_time": "2017-01-01T15:05:05Z",
          "comment": "string"
        }
      ]
    }
  ],
  "approver_can_revoke": true,
  "target_role_revoked": true,
  "target_role_revocation_time": "2017-01-01T15:05:05Z",
  "target_role_revoked_by": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string",
    "deleted": true
  }
}
delete/workflow-engine/api/v1/requests/{request_id}

Delete Request item by ID.

request_idstring

required

Request ID

Responses

Response examples

Request item successfully deleted

Empty response

post/workflow-engine/api/v1/requests/{request_id}/decision

Update a request in queue. Only users with matching role are permitted to change the status of a step requiring such role.

stepint

Workflow step requires approval

decisionstring

The user's decision

Enum
  • WAITING
  • APPROVED
  • DENIED
commentstring

A comment accompanying the decision

Responses

Request examples

{
  "step": 123,
  "decision": "WAITING",
  "comment": "string"
}

Response examples

Decision recorded

Empty response

post/workflow-engine/api/v1/requests/{request_id}/role/revoke

Revoke the target user role. Only original approvers of the request can revoke a role this way.

request_idstring

required

Request item ID

Responses

Response examples

Role revoked

Empty response

post/workflow-engine/api/v1/requests/search

Search access requests

keywordsstring
Example
"GRANT"
start_timestring
Format
date-time
Example
"2017-01-01T15:05:05Z"
end_timestring
Format
date-time
Example
"2017-01-01T15:05:05Z"
filterstring
Example
"requests"

Responses

Request examples

{
  "keywords": "GRANT",
  "start_time": "2017-01-01T15:05:05Z",
  "end_time": "2017-01-01T15:05:05Z",
  "filter": "requests"
}

Response examples

Successful response, returns an array of requests, returns an empty array if no requests found

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "requester": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      },
      "requested_role": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "name": "string",
        "deleted": true
      },
      "request_justification": "string",
      "grant_type": "string",
      "grant_start": "2017-01-01T15:05:05Z",
      "grant_end": "2017-01-01T15:05:05Z",
      "floating_length": 24,
      "max_floating_duration": 48,
      "max_time_restricted_duration": 15,
      "target_user": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      },
      "target_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "requestor_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "action": "GRANT",
      "created": "2017-01-01T15:05:05Z",
      "updated": "2017-01-01T15:05:05Z",
      "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "name": "An example workflow",
      "status": "WAITING",
      "comment": "A comment",
      "can_bypass_revoke_workflow": true,
      "steps": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "match": "ALL",
          "approvers": [
            {
              "id": "5bf77342-221c-11ee-be56-0242ac120002",
              "role": {
                "id": "5bf77342-221c-11ee-be56-0242ac120002",
                "name": "string",
                "deleted": true
              },
              "decision": "WAITING",
              "user": {
                "id": "5bf77342-221c-11ee-be56-0242ac120002",
                "display_name": "string"
              },
              "decision_time": "2017-01-01T15:05:05Z",
              "comment": "string"
            }
          ]
        }
      ],
      "approver_can_revoke": true,
      "target_role_revoked": true,
      "target_role_revocation_time": "2017-01-01T15:05:05Z",
      "target_role_revoked_by": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string",
        "deleted": true
      }
    }
  ]
}

Was this page helpful?