Skip to main content

Submit an Access Request

POST 
/access-requests

This submits the access request into IdentityNow, where it will follow any IdentityNow approval processes.

Access requests are processed asynchronously by IdentityNow. A success response from this endpoint means the request has been submitted to IDN and is queued for processing. Because this endpoint is asynchronous, it will not return an error if you submit duplicate access requests in quick succession, or you 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 access request status or the pending access request approvals endpoints. You can also use the search API to check the existing access items that an identity has before submitting an access request to ensure you are not requesting access that is already granted.

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.
  • While requesting entitlements, maximum of 25 entitlements and 10 recipients are allowed in a request.

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 access will be removed on that date and time only for roles and access profiles. Entitlements are currently unsupported for removeDate.
  • Roles, access profiles, and entitlements can be requested for revocation.
  • Revoke requests for entitlements are limited to 1 entitlement per access request currently.
  • [Roles, Access Profiles] You can specify a removeDate if the access doesn't already have a sunset date. The removeDate must be a future date, in the UTC timezone.
  • Allows a manager to request to revoke access for direct employees. A token with ORG_ADMIN authority can also request to revoke access from anyone.

Note: There is no indication to the approver in the IdentityNow UI that the approval request is for a revoke action. Take this into consideration when calling this API.

A token with API authority cannot be used to call this endpoint.

Request​

Body

required
    requestedFor string[]required

    A list of Identity IDs for whom the Access is requested. If it's a Revoke request, there can only be one Identity ID.

    requestType AccessRequestTypenullable

    Possible values: [GRANT_ACCESS, REVOKE_ACCESS, null]

    Access request type. Defaults to GRANT_ACCESS. REVOKE_ACCESS type can only have a single Identity ID in the requestedFor field.

    requestedItems object[]required

    Possible values: >= 1, <= 25

  • Array [
    • type stringrequired

    Possible values: [ACCESS_PROFILE, ROLE, ENTITLEMENT]

    The type of the item being requested.

    id stringrequired

    ID of Role, Access Profile or Entitlement being requested.

    comment string

    Comment provided by requester.

    • Comment is required when the request is of type Revoke Access.
    clientMetadata object

    Arbitrary key-value pairs. They will never be processed by the IdentityNow system but will be returned on associated APIs such as /account-activities and /access-request-status.

    property name* string
    removeDate date-time

    The date the role or access profile is no longer assigned to the specified identity. Also known as the expiration date.

    • Specify a date in the future.
    • The current SLA for the deprovisioning is 24 hours.
    • This date can be modified to either extend or decrease the duration of access item assignments for the specified identity. You can change the expiration date for requests for yourself or direct reports, but you cannot remove an expiration date on an already approved item. If the access request has not been approved, you can cancel it and submit a new one without the expiration. If it has already been approved, then you have to revoke the access and then re-request without the expiration.
    • Currently it is not supported for entitlements.
  • ]
    • clientMetadata object

    Arbitrary key-value pairs. They will never be processed by the IdentityNow system but will be returned on associated APIs such as /account-activities.

    property name* string

Responses​

Accepted - Returned if the request was successfully accepted into the system.

Schema

    object

Loading...