Skip to main content
POST
Create 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

Body

application/json

Request body for creating a pre-approval rule. Leaving every entitlements field unset is the same as request_has_entitlements: false, which covers only a request for the app itself.

justification
string
required

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

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.

Required. Every rule must limit who it applies to, so leaving condition out returns 400.

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.