Skip to main content
PATCH
Update Pre Approval Rule

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

app_uuid
string
required
pre_approval_rule_id
string
required

Body

application/json

Request body for updating a pre-approval rule. A field you leave out keeps the rule's current value, and a field you set to null is cleared.

The three entitlements fields are replaced together. If you send any of them, the rule's entitlements are replaced by the one you set. If every one you send is null, the rule covers only a request for the app itself. If you send none of them, the rule's entitlements stay as they are.

justification
string | null

Justification shown to requesters and reviewers for why this rule exists. Leave it out to keep the current value. It cannot be null.

Maximum string length: 500
condition
object | null

Who this rule pre-approves, and for how long they can have access.

A condition is either a single check or several checks combined. A single check looks like {"attribute": {"label": "<name>", "value": "<path>"}, "<operator>": <value>} and uses exactly one operator. To require every check to match, wrap them in {"and": [...]}. To require at least one to match, wrap them in {"or": [...]}. To match the opposite of a check, wrap it in {"not": {...}}.

Only the attributes below are accepted, and each one accepts only the operators listed for it. Any other attribute or operator returns 400.

  • identity.groups[*].external_id accepts contains_any. The value is a list of {"label": "<group name>", "value": "<group ID>"}, where the group ID is the ID the group has in the app it comes from. The check matches a person who belongs to any of the listed groups.
  • identity.email, identity.team, identity.title, and identity.status accept equals, !=, in, exists, contains, starts_with, and ends_with.
  • identity.start_date and identity.end_date accept equals, !=, >, >=, <, <=, in, and exists.
  • identity.source_app.id accepts equals, !=, in, and exists.
  • identity.custom_attributes["<Key>"] checks a custom attribute your organization has defined. For an attribute whose value is a person, use identity.custom_attributes["<Key>"].id. For an attribute whose value is a group, use identity.custom_attributes["<Key>"].external_id. It accepts the same operators as the attributes above that have the same value type. To match any of several values, use in with a list of {"label": "<display name>", "value": "<value>"}.
  • webhook.responses["<webhook ID>"] checks the response of one of your organization's pre-approval webhooks, which is called when the request is evaluated. It accepts only equals with the value "PREAPPROVED", and can't be inside a not. The check matches when the webhook pre-approves the request.
  • identity.oncall["<schedule ID>"].on_call checks whether the person is on call for an on-call schedule when the request is evaluated. The schedule ID is the schedule's entitlement ID. It accepts only equals with the value true, and can't be inside a not.
  • access_request.access_length accepts equals, !=, >, >=, <, <=, and in. Values are in seconds, for example {"label": "<display name>", "value": <seconds>}. To match unlimited access, use the value 2147483647 (2**31 - 1). Leaving this attribute out allows any duration, unlimited included.

Leave it out to keep the current value. It cannot be null, because every rule must limit who it applies to.

request_includes_entitlements
string[] | null

IDs of the entitlements this rule covers. The rule does not cover a request for any other entitlement. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.

Minimum array length: 1
request_does_not_include_entitlements
string[] | null

IDs of the entitlements this rule does not cover. The rule covers every other entitlement, and also a request for the app itself with no entitlement attached. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.

Minimum array length: 1
request_has_entitlements
boolean | null

true covers a request for any entitlement of this app, so you don't need to keep a list of IDs up to date. false covers only a request for the app itself with no entitlement attached. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.

Response

Successful Response

A rule that pre-approves matching access requests for an app.

id
string
required

UUID of this pre-approval rule.

app_id
string
required

UUID of the app this pre-approval rule applies to.

justification
string
required

Justification shown to requesters and reviewers for why this rule exists.

condition
object | null

Who this rule pre-approves, and for how long they can have access.

A condition is either a single check or several checks combined. A single check looks like {"attribute": {"label": "<name>", "value": "<path>"}, "<operator>": <value>} and uses exactly one operator. To require every check to match, wrap them in {"and": [...]}. To require at least one to match, wrap them in {"or": [...]}. To match the opposite of a check, wrap it in {"not": {...}}.

Only the attributes below are accepted, and each one accepts only the operators listed for it. Any other attribute or operator returns 400.

  • identity.groups[*].external_id accepts contains_any. The value is a list of {"label": "<group name>", "value": "<group ID>"}, where the group ID is the ID the group has in the app it comes from. The check matches a person who belongs to any of the listed groups.
  • identity.email, identity.team, identity.title, and identity.status accept equals, !=, in, exists, contains, starts_with, and ends_with.
  • identity.start_date and identity.end_date accept equals, !=, >, >=, <, <=, in, and exists.
  • identity.source_app.id accepts equals, !=, in, and exists.
  • identity.custom_attributes["<Key>"] checks a custom attribute your organization has defined. For an attribute whose value is a person, use identity.custom_attributes["<Key>"].id. For an attribute whose value is a group, use identity.custom_attributes["<Key>"].external_id. It accepts the same operators as the attributes above that have the same value type. To match any of several values, use in with a list of {"label": "<display name>", "value": "<value>"}.
  • webhook.responses["<webhook ID>"] checks the response of one of your organization's pre-approval webhooks, which is called when the request is evaluated. It accepts only equals with the value "PREAPPROVED", and can't be inside a not. The check matches when the webhook pre-approves the request.
  • identity.oncall["<schedule ID>"].on_call checks whether the person is on call for an on-call schedule when the request is evaluated. The schedule ID is the schedule's entitlement ID. It accepts only equals with the value true, and can't be inside a not.
  • access_request.access_length accepts equals, !=, >, >=, <, <=, and in. Values are in seconds, for example {"label": "<display name>", "value": <seconds>}. To match unlimited access, use the value 2147483647 (2**31 - 1). Leaving this attribute out allows any duration, unlimited included.

null when the rule is limited by a webhook, an on-call schedule, or an access policy instead. This API can't show those limits.

request_includes_entitlements
string[] | null

IDs of the entitlements this rule covers. The rule does not cover a request for any other entitlement. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.

Minimum array length: 1
request_does_not_include_entitlements
string[] | null

IDs of the entitlements this rule does not cover. The rule covers every other entitlement, and also a request for the app itself with no entitlement attached. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.

Minimum array length: 1
request_has_entitlements
boolean | null

true covers a request for any entitlement of this app, so you don't need to keep a list of IDs up to date. false covers only a request for the app itself with no entitlement attached. Exactly one of request_includes_entitlements, request_does_not_include_entitlements, and request_has_entitlements decides which requested entitlements this rule pre-approves. Responses include only that field. In requests, leave the other two out or set them to null. When a request asks for several entitlements, the rule checks each one separately.