Skip to main content

Submit access request

POST 
/access-requests/v1

Use this API to submit an access request in Identity Security Cloud (ISC), where it follows any ISC approval processes.

Security: idn:access-request:manage is for ORG_ADMIN level. idn:access-request-self:manage is for USER level.

info

The ability to request access using this API is constrained by the Access Request Segments defined in the API token's user context.

Access requests are processed asynchronously by ISC. A successful response from this endpoint means that the request has been submitted to ISC and is queued for processing. Because this endpoint is asynchronous, it does not return an error if you submit duplicate access requests in quick succession or submit an access request for access that is already in progress, approved, or rejected.

It is best practice to check for any existing access requests that reference the same access items before submitting a new access request. This can be accomplished by using the List Access Request Status or the Pending Access Request Approvals APIs. You can also use the Search API to check the existing access items an identity has before submitting an access request to ensure that you aren't requesting access that is already granted. If you use this API to request access that an identity already has, without changing the account details or end date information from the existing assignment, the API will cancel the request as a duplicate.

There are two types of access request:

GRANT_ACCESS

  • Can be requested for multiple identities in a single request.
  • Supports self request and request on behalf of other users. Refer to the Get Access Request Configuration endpoint for request configuration options.
  • Allows any authenticated token (except API) to call this endpoint to request to grant access to themselves. Depending on the configuration, a user can request access for others.
  • Roles, access profiles and entitlements can be requested.
  • You can specify a startDate to set or alter a sunrise date-time on an assignment. The startDate must be a future date-time, in the UTC timezone. Additionally, if the user already has the access assigned with a sunrise date and its yet to be provisioned, you can also submit a request without a startDate to request immediate provisioning after approval.
  • If a startDate is specified, then the requested role, access profile, or entitlement will be provisioned on that date and time.
  • You can specify a removeDate to set or alter a sunset date-time on an assignment. The removeDate must be a future date-time, in the UTC timezone. Additionally, if the user already has the access assigned with a sunset date, you can also submit a request without a removeDate to request removal of the sunset date and time.
  • If a removeDate is specified, then the requested role, access profile, or entitlement will be removed on that date and time.
  • Now supports an alternate field 'requestedForWithRequestedItems' for users to specify account selections while requesting items where they have more than one account on the source.

MACHINE IDENTITY ACCESS REQUESTS

  • Machine identity access requests reuse this same endpoint. They must use requestedForWithRequestedItems with identityType: MACHINE on each entry. Do not use the flat requestedFor / requestedItems shape for machines. Mixed human and machine identities in one request are not supported.
  • Request identityType uses HUMAN / MACHINE. List, status, and approval responses use IDENTITY / MACHINE_IDENTITY on requestedFor.type for the same distinction.

Prerequisites and authorization:

  • The organization must have Machine Identity Security licensed; otherwise the request is rejected with 403.
  • Access request config v2 machineIdentityAccessRequestEnabled must be true (default true); otherwise 403.
  • Request-on-behalf-of for machines is controlled by allowRequestOnBehalfOfForMachineIdentity and allowRequestForMachineByOwner on the access request configuration. See those schema fields for the authorization cascade (open ROBO, owner/admin ROBO, then admin-only fallback).

Constraints for machine requests:

  • Only ENTITLEMENT items are supported (roles and access profiles are rejected).
  • GRANT_ACCESS and MODIFY_ACCESS requests require accountSelection to be provided with accountUuid and/or nativeIdentity that match a real machine account for that machine identity on the selected source. Prefer values returned by the accounts-selection API.
  • MODIFY_ACCESS requests additionally require each item to have startDate and/or removeDate to denote date modifications.
  • REVOKE_ACCESS must target exactly one machine identity. Per entitlement item, provide nativeIdentity (or it may be auto-resolved when the machine has exactly one account on the entitlement source). Do not send accountSelection on machine revoke.
  • Multi-machine GRANT_ACCESS is allowed within existing recipient limits; multi-machine REVOKE_ACCESS is not.

FORMS IN ACCESS REQUESTS

  • Forms apply to human GRANT_ACCESS requests for roles, access profiles, and entitlements. Forms are not used for REVOKE_ACCESS.
  • Roles, access profiles, and entitlements can optionally reference a formDefinitionId in their request configuration. When configured, the requester completes that form and includes the resulting formInstanceId on each affected GRANT_ACCESS line item when submitting the access request.
  • Provide formInstanceId on each GRANT_ACCESS line item in requestedItems (flat payload) or in requestedForWithRequestedItems.requestedItems (nested payload). An empty formInstanceId on a GRANT_ACCESS line item is rejected with HTTP 400.
  • When a configured form is required, a missing formInstanceId, a submitted form whose definition does not match the configured formDefinitionId, or form instance data that could not be read may fail the request during asynchronous processing even when this endpoint returns success.
  • Reusing the same formInstanceId for the same requested object across multiple recipients is supported.
  • Completed form answers are returned on access request status, administration, and approval responses in the form object on each item. Access request pre-approval and dynamic approver trigger inputs may include form on each entry in requestedItems. The post-approval trigger includes form on each entry in requestedItemsStatus.
caution

If any entitlements are being requested, then the maximum number of entitlements that can be requested is 25, and the maximum number of identities that can be requested for is 10. If you exceed these limits, the request will fail with a 400 error. If you are not requesting any entitlements, then there are no limits.

REVOKE_ACCESS

  • Can only be requested for a single identity at a time.
  • You cannot use an access request to revoke access from an identity if that access has been granted by role membership or by birthright provisioning.
  • Does not support self request. Only manager can request to revoke access for their directly managed employees.
  • If a removeDate is specified, then the requested role, access profile, or entitlement will be removed on that date and time.
  • Roles, access profiles, and entitlements can be requested for revocation.
  • Revoke requests for entitlements are limited to 1 entitlement per access request currently.
  • You cannot specify a 'startDate' in a REVOKE_ACCESS request, as startDate is only applicable for GRANT_ACCESS requests to indicate when the access should be provisioned, and it does not make sense in the context of revoking access.
  • You can specify a removeDate to add or alter a sunset date and time on an assignment. The removeDate must be a future date-time, in the UTC timezone. If the user already has the access assigned with a sunset date and time, the removeDate must be a date-time earlier than the existing sunset date and time.
  • Allows a manager to request to revoke access for direct employees. A user with ORG_ADMIN authority can also request to revoke access from anyone.
  • Now supports REVOKE_ACCESS requests for identities with multiple accounts on a single source, with the help of 'assignmentId' and 'nativeIdentity' fields. These fields should be used within the 'requestedItems' section for the revoke requests.
  • For human identities, usage of 'requestedForWithRequestedItems' is not supported for revoke requests. Machine identity revoke requests must use 'requestedForWithRequestedItems' with identityType: MACHINE as described above.

Request​

Responses​

Access Request Response.