Requests

Quick Navigation

For more information on related topics, please see Credentials.

GET Requests

Purpose

Lists requests for the current user.

Query Parameters

  • status: (optional, default: all) Status of requests to return.
    • all: Both active and pending requests.
    • active: Requests that have been approved (including auto-approved).
    • pending: Requests that have not yet been approved.
  • queue: (optional, default: req): Type of request queue to return.
    • req: Requestor queue, returns requests available to the user as a requestor.
    • app: Approver queue, returns requests for an approver or requestor/approver that have either been approved by the user (active) or have not yet been approved (pending).

Request Body

None.

Response Body

Content-Type: application/json

[
    {
        RequestID: int,
        SystemID: int,
        SystemName: string,
        AccountID: int,
        AccountName: string,
        DomainName: string,
        AliasID: int,
        ApplicationID: int,
        RequestReleaseDate: date-formatted string,
        ApprovedDate: date-formatted string,
        ExpiresDate: date-formatted string,
        Status: string,
        AccessType: string
    },
    …
]

Response Codes

  • 200 – Request successful. Requests in the response body.
  • 403 – Access forbidden. Response body contains a message or status code indicating the reason for this forbidden access:
    • 4033 – Approver Only API or account. Only Approvers can access this API or account.

For more information, please see Common Response Codes.

POST Requests

Purpose

Creates a new release request.

Required Roles

  • Requestor or requestor/approver role to managed account referenced by ID

For information on ISA role access, please see ISA Requests.

Request Body

Content-Type: application/json

{
    AccessType: string,
    SystemID: int,
    AccountID: int,
    ApplicationID: int, // can be null
    DurationMinutes : int,
    Reason : string,
    AccessPolicyScheduleID : int, // can be null
    ConflictOption : string,
    TicketSystemID : int,
    TicketNumber : string,
    RotateOnCheckin: bool
}

Request Body Details

  • AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
    • View: View Password access.
    • RDP: RDP access (corresponds to POST Sessions SessionType RDP or rdpfile).
    • SSH: SSH access (corresponds to POST Sessions SessionType SSH).
    • App: Application access (corresponds to POST Sessions SessionType App or appfile).
  • SystemID: (required) ID of the managed system to request.
  • AccountID: (required) ID of the managed account to request.
  • ApplicationID: (required when AccessType=App): ID of the application for an application-based request.
  • DurationMinutes: (required: 1-525600) The request duration (in minutes).
  • Reason: (optional) The reason for the request.
  • AccessPolicyScheduleID: (optional) The schedule ID of an access policy to use for the request. If omitted, automatically selects the best schedule.
  • ConflictOption: (optional) The conflict resolution option to use if an existing request is found for the same user, system, and account (reuse, renew). If omitted and a conflicting request is found, returns a 409 code (see below).
    • reuse: Returns an existing, approved request ID for the same user/system/account/access type (if one exists). If the request does not already exist, creates a new request using the request body details.
    • renew: Cancels any existing approved requests for the same user/system/account and creates a new request using the request body details.
  • TicketSystemID: ID of the ticket system. If omitted, then default ticket system will be used.
  • TicketNumber: Number of associated ticket. Can be required if ticket system is marked as required in the access policy used. Max string length is 20.
  • RotateOnCheckin: (optional, default: true) True to rotate the credentials on check-in/expiry, otherwise false. This property can only be used if the access policy (either auto-selected or given in AccessPolicyScheduleID) supports it.

In reference to RotateOnCheckin, If the Managed Account given in AccountID does not rotate the credentials after check-in/expiry, this setting is ignored.

For more information, please see the Allow API Rotation Override access policy setting under View access.

Response Body

{
    RequestID: int
}

Response Codes

  • 200 – Existing request is being reused. Existing request ID in the response body.
  • 201 – Request successful. Request ID in the response body.
  • 403 – User does not have permissions to request the indicated account or the account does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
    • 4031 – User does not have permission to request the account or the account is not valid for the system.
    • 4033 – Approver Only API or account. Only Approvers can access this API or account.
    • 4035 - Not enough Approvers configured to approve a request.
  • 409 – Conflicting request exists. This user or another user has already requested a password for the specified account within the next <durationMinutes> window.

For more information, please see Common Response Codes.

POST Aliases/{aliasId}/Requests

Purpose

Creates a new release request using an alias.

Required Roles

Requestor or requestor/approver role to managed account referenced by the alias.

URL Parameters

aliasId: ID of the managed account alias.

Request Body

Content-Type: application/json

{
    AccessType: string,
    DurationMinutes : int,
    Reason : string,
    AccessPolicyScheduleID : int, // can be null
    ConflictOption : string,
    TicketSystemID : int,
    TicketNumber : string,
    RotateOnCheckin: bool
}

Request Body Details

  • AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
    • View: View password access.
    • RDP: RDP access (corresponds to POST Sessions SessionType RDP or rdpfile).
    • SSH: SSH access (corresponds to POST Sessions SessionType SSH).
  • DurationMinutes: (required: 1-525600): The request duration (in minutes).
  • Reason: (optional) The reason for the request.
  • AccessPolicyScheduleID: (optional) The schedule ID of an access policy to use for the request. If omitted, automatically selects the best schedule.
  • ConflictOption: (optional) The conflict resolution option to use if an existing request is found for the same user, system, and account (reuse, renew). If omitted and a conflicting request is found, returns a 409 (see below).
    • reuse: Return an existing, approved request ID for the same user/system/account/access type (if one exists). If the request does not already exist, creates a new request using the request body details.
    • renew: Cancel any existing approved requests for the same user/system/account and create a new request using the request body details.
  • TicketSystemID: ID of the ticket system. If omitted then default ticket system is used.
  • TicketNumber: Number of associated ticket. Can be required if ticket system is marked as required in the access policy used. Max string length is 20.
  • RotateOnCheckin: (optional, default: true) True to rotate the credentials on check-in/expiry, otherwise false. This property can only be used if the access policy (either auto-selected or given in AccessPolicyScheduleID) supports it. If the managed account given in AccountID does not rotate the credentials after check-in/expiry, this setting is ignored.

For more information, please see the Allow API Rotation Override access policy setting under View access.

Response Body

{
    RequestID: int
}

Response Codes

  • 200 – Existing request is being reused. Existing request ID in the response body.
  • 201 – Request successful. Request ID in the response body.
  • 403 – User does not have permissions to request the indicated alias or the account referenced by the alias does not have API access enabled. Response body contains a status code indicating the reason for this forbidden access:
    • 4031 – User does not have permission to request the account or the account is not valid for the system.
    • 4033 – Approver Only API or account. Only Approvers can access this API or account.
    • 4035 - Not enough approvers configured to approve a request.
  • 409 – Conflicting request exists. This user or another user has already requested a password for the specified account within the next <durationMinutes> window.

For more information, please see Common Response Codes.

PUT Requests/{id}/Checkin

Alternate URI (deprecated)

PUT Requests/Release/{id}

Purpose

Checks-in/releases a request before it has expired.

Required Roles

Requestor role to managed account referenced by the request.

URL Parameters

id: ID of the request to check-in/release.

Request Body

Content-Type: application/json

{
    Reason : string
}

Request Body Details

Reason: (optional) A reason or comment why the request is being released. Max string length is 1000.

Response Body

None.

Response Codes

  • 204 – Request successful. No content in body.
  • 403 – User does not have permissions to release the indicated request or the associated account does not have API access enabled. Message or status code in response body:
    • 4031 – User does not have permission to release a password.
    • 4034 – Request is not yet approved.

For more information, please see Common Response Codes.

PUT Requests/{id}/Approve

Purpose

Approves a pending request.

Required Roles

Approver or requestor/approver role to managed account referenced by the request.

URL Parameters

id: ID of the request to approve.

Request Body

Content-Type: application/json

{
    Reason : string
}

Request Body Details

Reason: (optional) A reason or comment why the request is being approved. Max string length is 1000.

Response Body

None.

Response Codes

  • 204 – Request successful. No content in body.
  • 403 – User does not have permissions to approve the indicated request or the associated account does not have API access enabled. Message or status code in response body:
    • 4033 – Approver only - User cannot approve his or her own request.
    • 4036 – Request has been approved already.

For more information, please see Common Response Codes.

PUT Requests/{id}/Deny

Purpose

Denies/cancels an active or pending request.

Required Roles

Approver or requestor/approver role to managed account referenced by the request.

URL Parameters

id: ID of the request to deny/cancel.

Request Body

Content-Type: application/json

{
    Reason : string
}

Request Body Details

Reason: (optional) A reason or comment why the request is being denied/cancelled. Max string length is 1000.

Response Body

None.

Response Codes

  • 204 – Request successful. No content in body.
  • 403 – User does not have permissions to deny the indicated request or the associated account does not have API access enabled. Message or status code in response body:
  • 4033 – Approver only - User cannot deny his or her own request.

For more information, please see Common Response Codes.

PUT Requests/{id}/RotateOnCheckin

Purpose

Updates a request to rotate the credentials on check-in/expiry.

If POST Requests RotateOnCheckin=false, this updates the request to true. If POST Requests RotateOnCheckin=true, the request is not modified.

Requirements

  • Current user must be the owner of the request.
  • Request must not be cancelled or expired.

URL Parameters

id: ID of the request to update.

Request Body

None.

Response Body

None.

Response Codes

204 – Request successful. No content in body.

For more information, please see Common Response Codes.