UpdateEntitlement

PATCH/api/v1/entitlements/{entitlement}

Update an entitlement, such as when the access it grants expires.

Example request

US
Europe

curl -X PATCH \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "string", "subject": "string" }' \
  "https://us.oblique.security/api/v1/entitlements/{entitlement}?updateMask=resource,subject"

Set OBLIQUE_API_KEY to your API key.

curl -X PATCH \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "string", "subject": "string" }' \
  "https://eu.oblique.security/api/v1/entitlements/{entitlement}?updateMask=resource,subject"

Set OBLIQUE_API_KEY to your API key.

Path parameters

entitlement.namestringrequired
Assigned by Oblique. Name of the entitlement of the format entitlements/{entitlement}.

Query parameters

updateMaskstring (field-mask)
The list of fields to update.
allowMissingboolean
If set to true, and the entitlement is not found, a new entitlement will be created with the given name. If created in this way, update_mask is ignored.

Request body

resourcestringrequired
Set once, when the resource is created. The resource that this entitlement grants access to.

Format: resources/{resource}
subjectstringrequired
Set once, when the resource is created. The subject that is granted access to the resource. This can be a user, team, group, an account in an integration, or another resource.

An account subject grants the access to that account rather than to the directory user behind it. The account must belong to the same integration as the resource.

A resource subject represents a nested membership in the system that owns both resources, such as a Google group that is a member of another Google group. Both resources must come from the same integration, and the system must support that pairing: a Google group nests in a Google group, an Okta group in an Okta app, and a GitHub team in a GitHub team. A resource can’t be a member of itself.

Format: users/{user}, teams/{team}, groups/{group}, integrations/{integration}/accounts/{account}, resources/{resource}
rolesRole[]
The roles the subject holds on the resource. A resource can grant a subject more than one role at once, such as a Cloudflare policy that carries several permission groups.

A subject holding the system’s default role has that role recorded explicitly, so an empty list means the roles are unknown rather than that the subject holds none.
- displayNamestringrequired
  The role’s name as the system that owns the resource names it. For example, a Google group membership is MEMBER, MANAGER, or OWNER, and a Cloudflare permission group has a name such as “OAuth App Registrations Read”.
  
  Every system names its roles differently, so values are recorded verbatim and are not validated.
- idstringrequired
  The identifier the system that owns the resource uses for this role. Opaque to Oblique, and the same as display_name for a system that names a role only one way.
One of
- expireTime
- ttl
- expireTimestring (date-time)
  If present, when this access expires. This field is always provided on output.
- ttlstring (duration)
  Input only. The TTL for the entitlement.
createTimestring (date-time)read-only
Create and update timestamps.
updateTimestring (date-time)read-only
justificationstring
Human readable justification for the entitlement to be granted. For example, this may contain a link to a ticket or other artifacts.
importedboolean
Set once, when the resource is created. When true, this boolean indicates this entitlement was “imported” from a syncing process, such as reading data from Okta or Google Groups. User created entitlements will always cause this field to be false or unset.
requeststringread-only
If present, the request that most recently created or updated this entitlement.

Format: requests/{request}
actionUpdateTimestring (date-time)read-only
When this entitlement was created, or the last time its roles changed.

If this entitlement is the result of a change in Oblique, it may not have been actuated to a remote system yet. See sync_action_update_time.
syncActionUpdateTimestring (date-time)read-only
The action_update_time when this entitlement was last observed to be in-sync with the remote system.

For imported entitlements, this will always match action_update_time, since Oblique observes the remote state at the same time it creates the entitlement.

For entitlements written to external systems, this is the action_update_time for the entitlement that was acted on.

sync_action_update_time is either older than action_update_time, indicating an entitlement hasn’t been pushed yet. Or equivalent to action_update_time when an entitlement has been reconciled.

Response

200Entitlement

An entitlement represents a permission or access right that can be granted to users or teams.

namestring
Assigned by Oblique. Name of the entitlement of the format entitlements/{entitlement}.
resourcestringrequired
Set once, when the resource is created. The resource that this entitlement grants access to.

Format: resources/{resource}
subjectstringrequired
Set once, when the resource is created. The subject that is granted access to the resource. This can be a user, team, group, an account in an integration, or another resource.

An account subject grants the access to that account rather than to the directory user behind it. The account must belong to the same integration as the resource.

A resource subject represents a nested membership in the system that owns both resources, such as a Google group that is a member of another Google group. Both resources must come from the same integration, and the system must support that pairing: a Google group nests in a Google group, an Okta group in an Okta app, and a GitHub team in a GitHub team. A resource can’t be a member of itself.

Format: users/{user}, teams/{team}, groups/{group}, integrations/{integration}/accounts/{account}, resources/{resource}
rolesRole[]
The roles the subject holds on the resource. A resource can grant a subject more than one role at once, such as a Cloudflare policy that carries several permission groups.

A subject holding the system’s default role has that role recorded explicitly, so an empty list means the roles are unknown rather than that the subject holds none.
- displayNamestringrequired
  The role’s name as the system that owns the resource names it. For example, a Google group membership is MEMBER, MANAGER, or OWNER, and a Cloudflare permission group has a name such as “OAuth App Registrations Read”.
  
  Every system names its roles differently, so values are recorded verbatim and are not validated.
- idstringrequired
  The identifier the system that owns the resource uses for this role. Opaque to Oblique, and the same as display_name for a system that names a role only one way.
One of
- expireTime
- ttl
- expireTimestring (date-time)
  If present, when this access expires. This field is always provided on output.
- ttlstring (duration)
  Input only. The TTL for the entitlement.
createTimestring (date-time)read-only
Create and update timestamps.
updateTimestring (date-time)read-only
justificationstring
Human readable justification for the entitlement to be granted. For example, this may contain a link to a ticket or other artifacts.
importedboolean
Set once, when the resource is created. When true, this boolean indicates this entitlement was “imported” from a syncing process, such as reading data from Okta or Google Groups. User created entitlements will always cause this field to be false or unset.
requeststringread-only
If present, the request that most recently created or updated this entitlement.

Format: requests/{request}
actionUpdateTimestring (date-time)read-only
When this entitlement was created, or the last time its roles changed.

If this entitlement is the result of a change in Oblique, it may not have been actuated to a remote system yet. See sync_action_update_time.
syncActionUpdateTimestring (date-time)read-only
The action_update_time when this entitlement was last observed to be in-sync with the remote system.

For imported entitlements, this will always match action_update_time, since Oblique observes the remote state at the same time it creates the entitlement.

For entitlements written to external systems, this is the action_update_time for the entitlement that was acted on.

sync_action_update_time is either older than action_update_time, indicating an entitlement hasn’t been pushed yet. Or equivalent to action_update_time when an entitlement has been reconciled.

Errors

Status	Meaning
`400`	Malformed request
`401`	Missing or invalid API key
`403`	Not allowed for this API key
`404`	Not found
`429`	Too many requests
`500`	Internal server error