Requests

Quick Navigation

For more information on related topics, please see Credentials.

GET Requests

Lists requests for the current user.

  • 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).

None

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
    },
    …
]
  • 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:
    • 4032 – Requestor Only API or account. Only Requestors can access this API or account.
    • 4033 – Approver Only API or account. Only Approvers can access this API or account.

For more information, please see Common Response Codes.

POST Requests

Creates a new release request.

  • Requestor or Requestor/Approver Role to Managed Account referenced by ID

For information on ISA role access, please see ISA Requests

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
}
  • AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
    • View: View Password access.
    • RDP: RDP access (corresponds to POST Sesssions SessionType RDP or rdpfile).
    • SSH: SSH access (corresponds to POST Sesssions SessionType SSH).
    • App: Application access (corresponds to POST Sesssions 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 theAccess 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.

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

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

{
    RequestID: int
}
  • 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.
    • 4032 – Requestor Only API or account. Only Requestors can access this API or account.
    • 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

Creates a new release request using an Alias.

Requestor or Requestor/Approver Role to Managed Account referenced by the Alias

aliasId: ID of the Managed Account Alias.

Content-Type: application/json

{
    AccessType: string,
    DurationMinutes : int,
    Reason : string,
    AccessPolicyScheduleID : int, // can be null
    ConflictOption : string,
    TicketSystemID : int,
    TicketNumber : string,
    RotateOnCheckin: bool
}
  • AccessType: (optional, default: View) The type of access requested (View, RDP, SSH, App).
    • View: View Password access.
    • RDP: RDP access (corresponds to POST Sesssions SessionType RDP or rdpfile).
    • SSH: SSH access (corresponds to POST Sesssions 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 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. 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.

{
    RequestID: int
}
  • 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.
    • 4032 – Requestor Only API or account. Only Requestors can access this API or account.
    • 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

PUT Requests/Release/{id}

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

Requestor Role to Managed Account referenced by the request

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

Content-Type: application/json

{
    Reason : string
}

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

None

  • 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

Approves a pending request.

Approver or Requestor/Approver Role to Managed Account referenced by the request

id: ID of the Request to approve.

Content-Type: application/json

{
    Reason : string
}

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

None

  • 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

Denies/cancels an active or pending request.

Approver or Requestor/Approver Role to Managed Account referenced by the request

id: ID of the Request to deny/cancel.

Content-Type: application/json

{
    Reason : string
}

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

None

  • 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

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

If POST Requests RotateOnCheckin=false, this will update the request to true. If POST Requests RotateOnCheckin=true, the request will not be modified.

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

id: ID of the Request to update.

None

None

204 – Request successful. No content in body.

For more information, please see Common Response Codes.