requests

Download Spec

Create and act upon role requests
get /workflow-engine/api/v1/requests

Get the request queue for the user.

offset

int

Offset where to start fetching the items

Default
0

limit

int

Number of items to return

Default
50
Max
100

filter

string

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

Response

ExamplesSchema

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"
      },
      "requested_role": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "name": "string",
        "deleted": true
      },
      "request_justification": "string",
      "grant_type": "PERMANENT",
      "grant_types": [
        "PERMANENT"
      ],
      "grant_start": "2017-01-01T15:05:05Z",
      "grant_end": "2017-01-01T15:05:05Z",
      "floating_length": 24,
      "max_active_requests": 1,
      "max_floating_duration": 48,
      "max_time_restricted_duration": 15,
      "requested_grant_type": "PERMANENT",
      "requested_grant_start": "2017-01-01T15:05:05Z",
      "requested_grant_end": "2017-01-01T15:05:05Z",
      "requested_floating_length": 24,
      "target_user": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string"
      },
      "target_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "workflow": "5bf77342-221c-11ee-be56-0242ac120002",
      "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",
      "approver_can_revoke": true,
      "target_role_revoked": true,
      "target_role_revoked_by": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string"
      },
      "target_role_revocation_time": "2017-01-01T15:05:05Z",
      "can_bypass_revoke_workflow": true,
      "steps": [
        {
          "name": "string",
          "match": "ALL",
          "approvers": [
            {
              "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"
            }
          ]
        }
      ]
    }
  ]
}

post /workflow-engine/api/v1/requests

Add a workflow to the request queue.

id

string

uuid

The UUID of the returned object, unique to a workflow template and a request. [TR]

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

requester

object (requester)

The ID & display name of the user making the request [R]

requested_role

object (requested_role)

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

request_justification

string

Justification for the request [R]

grant_type

string

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. [R]

Enum
  • PERMANENT
  • TIME_RESTRICTED
  • FLOATING

grant_types

array[string]

List of role granting types. 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. [T]

grant_start

string

date-time

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

Example
"2017-01-01T15:05:05Z"

grant_end

string

date-time

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

Example
"2017-01-01T15:05:05Z"

floating_length

int

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

Example
24

max_active_requests

int

Maximum number of concurrent open requests a user can have per target role. Set to -1 to allow an unlimited number of open requests. Assumed 1 if not specified.

Example
1

max_floating_duration

int

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

Example
48

max_time_restricted_duration

int

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

Example
15

requested_grant_type

string

Requested grant type, 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. [R]

Enum
  • PERMANENT
  • TIME_RESTRICTED
  • FLOATING

requested_grant_start

string

date-time

Requested date & time after which the role is granted to the user. Can be overriden in decision phase. [R]

Example
"2017-01-01T15:05:05Z"

requested_grant_end

string

date-time

Requested date & time after which the role is removed from the user. Can be overriden in decision phase. [R]

Example
"2017-01-01T15:05:05Z"

requested_floating_length

int

Requested time in hours for which the grant should last after initial connection. Can be overriden in decision phase. [R]

Example
24

target_user

object (target_user)

The ID of the user the request is made for [R]

target_roles

array[object]

A list of roles this workflow targets [TR]

workflow

string

uuid

The ID of the workflow the request is based on [TR]

action

string

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. [TR]

Enum
  • GRANT
  • REMOVE
  • BOTH

created

string

date-time

When the object was created [TR]

Example
"2017-01-01T15:05:05Z"

updated

string

date-time

When the object was updated [TR]

Example
"2017-01-01T15:05:05Z"

updated_by

string

uuid

ID of the user who updated the object [TR]

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

author

string

uuid

ID of the user who originally authored the object [TR]

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

name

string

required

Name of the workflow [T]

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

status

string

Computed status for the instance of the workflow - based on step statuses [R]

Default
"WAITING"
Enum
  • WAITING
  • APPROVED
  • DENIED

comment

string

A comment describing the object [TR]

Example
"A comment"

approver_can_revoke

boolean

A flag used to determine if approvers can revoke a role from target user [R]

Default
false

target_role_revoked

boolean

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

Default
false

target_role_revoked_by

object (target_role_revoked_by)

User object of who revoked the target role [R]

target_role_revocation_time

string

date-time

Date and time of revocation [R]

Example
"2017-01-01T15:05:05Z"

can_bypass_revoke_workflow

boolean

A flag used to determine if approvers can bypass the revoke workflow to revoke a role [T]

Default
false

steps

array[object]

required

Array of steps [TR]

Request

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "requester": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "requested_role": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "name": "string",
    "deleted": true
  },
  "request_justification": "string",
  "grant_type": "PERMANENT",
  "grant_types": [
    "PERMANENT"
  ],
  "grant_start": "2017-01-01T15:05:05Z",
  "grant_end": "2017-01-01T15:05:05Z",
  "floating_length": 24,
  "max_active_requests": 1,
  "max_floating_duration": 48,
  "max_time_restricted_duration": 15,
  "requested_grant_type": "PERMANENT",
  "requested_grant_start": "2017-01-01T15:05:05Z",
  "requested_grant_end": "2017-01-01T15:05:05Z",
  "requested_floating_length": 24,
  "target_user": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "target_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "workflow": "5bf77342-221c-11ee-be56-0242ac120002",
  "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",
  "approver_can_revoke": true,
  "target_role_revoked": true,
  "target_role_revoked_by": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "target_role_revocation_time": "2017-01-01T15:05:05Z",
  "can_bypass_revoke_workflow": true,
  "steps": [
    {
      "name": "string",
      "match": "ALL",
      "approvers": [
        {
          "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"
        }
      ]
    }
  ]
}

Response

ExamplesSchema

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_id

string

required

Request item ID

Response

ExamplesSchema

Successful response, returns the request item if found

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "requester": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "requested_role": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "name": "string",
    "deleted": true
  },
  "request_justification": "string",
  "grant_type": "PERMANENT",
  "grant_types": [
    "PERMANENT"
  ],
  "grant_start": "2017-01-01T15:05:05Z",
  "grant_end": "2017-01-01T15:05:05Z",
  "floating_length": 24,
  "max_active_requests": 1,
  "max_floating_duration": 48,
  "max_time_restricted_duration": 15,
  "requested_grant_type": "PERMANENT",
  "requested_grant_start": "2017-01-01T15:05:05Z",
  "requested_grant_end": "2017-01-01T15:05:05Z",
  "requested_floating_length": 24,
  "target_user": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "target_roles": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "name": "string",
      "deleted": true
    }
  ],
  "workflow": "5bf77342-221c-11ee-be56-0242ac120002",
  "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",
  "approver_can_revoke": true,
  "target_role_revoked": true,
  "target_role_revoked_by": {
    "id": "5bf77342-221c-11ee-be56-0242ac120002",
    "display_name": "string"
  },
  "target_role_revocation_time": "2017-01-01T15:05:05Z",
  "can_bypass_revoke_workflow": true,
  "steps": [
    {
      "name": "string",
      "match": "ALL",
      "approvers": [
        {
          "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"
        }
      ]
    }
  ]
}

delete /workflow-engine/api/v1/requests/{request_id}

Delete Request item by ID.

request_id

string

required

Request ID

Response

ExamplesSchema

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.

step

int

Workflow step requires approval

decision

string

The user's decision

Enum
  • WAITING
  • APPROVED
  • DENIED

comment

string

A comment accompanying the decision

Request

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

Response

ExamplesSchema

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_id

string

required

Request item ID

Response

ExamplesSchema

Role revoked

Empty response

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

Search access requests

keywords

string

Example
"GRANT"

start_time

string

date-time

Example
"2017-01-01T15:05:05Z"

end_time

string

date-time

Example
"2017-01-01T15:05:05Z"

Request

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

Response

ExamplesSchema

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"
      },
      "requested_role": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "name": "string",
        "deleted": true
      },
      "request_justification": "string",
      "grant_type": "PERMANENT",
      "grant_types": [
        "PERMANENT"
      ],
      "grant_start": "2017-01-01T15:05:05Z",
      "grant_end": "2017-01-01T15:05:05Z",
      "floating_length": 24,
      "max_active_requests": 1,
      "max_floating_duration": 48,
      "max_time_restricted_duration": 15,
      "requested_grant_type": "PERMANENT",
      "requested_grant_start": "2017-01-01T15:05:05Z",
      "requested_grant_end": "2017-01-01T15:05:05Z",
      "requested_floating_length": 24,
      "target_user": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string"
      },
      "target_roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "deleted": true
        }
      ],
      "workflow": "5bf77342-221c-11ee-be56-0242ac120002",
      "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",
      "approver_can_revoke": true,
      "target_role_revoked": true,
      "target_role_revoked_by": {
        "id": "5bf77342-221c-11ee-be56-0242ac120002",
        "display_name": "string"
      },
      "target_role_revocation_time": "2017-01-01T15:05:05Z",
      "can_bypass_revoke_workflow": true,
      "steps": [
        {
          "name": "string",
          "match": "ALL",
          "approvers": [
            {
              "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"
            }
          ]
        }
      ]
    }
  ]
}

Was this page helpful?