Skip to main content
This guide covers the changes specific to access requests and tasks. For the conventions every endpoint shares, see What changes in v1.

​
Access requests

​
Filing a request

Create Access Request keeps every body field except requestable_permission_ids, which becomes entitlement_ids.
Requestable-permission IDs stored from v0 don’t work in entitlement_ids. A v0 ID sent as an entitlement ID returns 404 with code set to access_request.entitlement_not_found. A body that still sends requestable_permission_ids returns 400. Migrate requestable permissions to entitlements covers the ID change.
v0
v1
The call returns 201 with a response like this:
v1 response
An access_length that the app doesn’t offer returns 400. v0 returned 422.

​
Reading requests

List Access Requests and Get Access Request have the same filters and expansions across versions: user_id, requester_user_id, target_user_id, statuses, and expand. The list uses page tokens, like every v1 list. Beyond that, four things change:
  • Entitlements replace requestable permissions. v0 listed what was requested under requestable_permissions, as full requestable-permission objects. v1 lists entitlements instead, as described in Entitlements on a request.
  • sort is now order_by. Send order_by=created_at for oldest first, which is the default, or order_by=created_at desc for newest first. A sort parameter returns 400 with code set to validation.unknown_query_parameter.
  • status and statuses take labels. See Status values.
  • Embedded tasks are v1 tasks. With expand=tasks, each task has the shape and values that Tasks describes.
Who can see a request hasn’t changed, as Who can see a request describes.

​
Status values

status in responses and statuses in filters take lowercase kebab-case labels. notes is keyed by the same labels. A v0 value in statuses returns 400. The embedded users’ status is a label too, such as active. For every user status, see The User object.

​
Cancelling a request

v0 cancelled with DELETE and took the reason as a query parameter. v1 cancels with the :cancel custom method and takes the reason in an optional JSON body:
v1
  • Both versions return 204.
  • Send the reason in the body. A reason query parameter returns 400 with code set to validation.unknown_query_parameter.
  • If the request’s status no longer allows cancelling, the call returns 409. v0 returned 422. Cancelling lists the statuses you can cancel from.

​
Tasks

​
Listing tasks

Both versions of List Tasks list only the tasks you can see, as Which tasks you can see describes. Both list only open tasks (pending, accepted, and blocked) unless you pass status. v1 renames or replaces seven v0 parameters: status, product_area, search, assigned_group_ids, access_request_id, show_all_tasks, and expand keep their names. status and product_area take v1’s labels. To sort in descending order, add desc after the field, as in order_by=created_at desc, which is order_by=created_at%20desc in a URL. Without order_by, v1 lists newest first.
A v0 parameter name sent to v1, such as task_type or sort_by, returns 400 with code set to validation.unknown_query_parameter.
v1 checks parameter names and values. status=PENDING returns 400, because v1 expects pending. Filtering the list lists the other values that return an error. To list your open approval tasks, 50 at a time:
v0
v1
v1 response

​
Task fields

  • entitlement_id holds an entitlement ID, not the requestable-permission ID that requestable_permission_id held. Entitlement IDs on tasks covers when it’s null.
  • v0’s task endpoints omitted fields that had no value. v1 returns them as null. The exceptions are assignees, actions, and comments, which appear only when you name them in expand.

​
Values

type, category, status, and product_area take lowercase kebab-case labels in v1, in responses and in filters alike. An unknown value in any of the four filters returns 400. Some v1 types cover more than one v0 type. Filtering by one of those labels returns tasks of every v0 type behind it. The same status labels appear in transition_to, both in the actions a task lists and in the body of Perform Task Action. With expand=assignees, an assignee’s type is user or group. v0 returned USER or GROUP.

​
Acting on a task

Complete, dismiss, and reassign work as they did on v0, with the same bodies and the same status code on success. v1 adds a code to several of their errors, which Acting on a task lists. Perform Task Action accepts different values:
  • action_type takes a label, such as approve-access-request rather than APPROVE_SUPPORT_REQUEST. The labels a task accepts are the action_type values in its actions, which List Task Actions returns, as does List Tasks with expand=actions. A v0 action type returns 400 with code set to task.action_unknown.
  • transition_to takes a status label, such as completed rather than COMPLETED. It must be one of the transitions the action lists. Otherwise the call returns 400 with code set to task.transition_not_allowed.
Create Task Comment returns 201 on both versions. v0’s response had no body. v1’s response is the comment it created, with body, created_by, and created_at.

​
Task types v1 doesn’t return

AGENT_ISSUE tasks have no v1 label. v0’s task list already omitted them. v1 also omits them from an access request’s tasks, and reading or acting on one by ID returns 404.