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",
        "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.

id

string

uuid

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

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

requester

object (requester)

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

requested_role

object (requested_role)

required

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

request_justification

string

Justification for the access request.

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.

grant_start

string

date-time

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

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.

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.

Example
24

max_floating_duration

int

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

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.

Example
15

target_user

object (target_user)

The ID of the user the request is made for.

target_roles

array[object]

A list of roles this workflow targets.

requestor_roles

array[object]

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

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.

Enum
  • GRANT
  • REMOVE
  • BOTH

created

string

date-time

When the object was created.

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

updated

string

date-time

When the object was updated.

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

updated_by

string

uuid

ID of the user who updated the object.

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

author

string

uuid

ID of the user who originally authored the object.

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

name

string

Name of the workflow.

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

status

string

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

Default
"WAITING"
Enum
  • WAITING
  • APPROVED
  • DENIED

comment

string

A comment describing the object.

Example
"A comment"

can_bypass_revoke_workflow

boolean

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

Default
false

steps

array[object]

Array of steps.

approver_can_revoke

boolean

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

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.

Default
false

target_role_revocation_time

string

date-time

Date and time of revocation.

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

target_role_revoked_by

object (target_role_revoked_by)

User object of who revoked the target role.

Request

{
  "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

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",
    "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_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"

filter

string

Example
"requests"

Request

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

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",
        "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?