ListEntitlements

GET/api/v1/entitlements

List or search for the underlying set of access that a user, group, or team has to a Resource.

Resources are low-level APIs that represent external objects, and users should be shown Listings and ListingRoles instead. Use ListListingRoleEffectiveSubjects to determine what a user or team has access to.

Example request

US

curl \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  "https://us.oblique.security/api/v1/entitlements"

Set OBLIQUE_API_KEY to your API key.

Europe

curl \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  "https://eu.oblique.security/api/v1/entitlements"

Set OBLIQUE_API_KEY to your API key.

Query parameters

• pageSizeinteger (int32)

  The maximum number of entitlements to return. This service may return fewer than this value.

• pageTokenstring

  A page token, received from a previous ListEntitlements call.

• filterstring

  Entitlements may be filtered by the subject they apply to, the resource or resources they grant access to, or the integration that reports those resources. More advanced filters are rejected.

  Examples:

  • subject="teams/{team}"
  • subject="users/{user}" or subject="users/me"
  • subject="integrations/{integration}/accounts/{account}"
  • subject="resources/{resource}"
  • resource="resources/{resource}"
  • resource="resources/{resource},resources/{resource}"
  • integration="integrations/{integration}"

  A resource can appear on either side, and the two are opposites. Filtering by subject returns the entitlements nesting that resource inside others; filtering by resource returns the entitlements granting access to it. The resource filter accepts a comma-separated list of resources; filtering by integration returns the entitlements granting access to any resource that integration reports.

• showDeletedboolean

  If true, the response will include entitlements in resources that have been deleted.

Response

200ListEntitlementsResponse

• entitlementsEntitlement[]
  • namestring

    Assigned by Oblique.

  • 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

    • expireTimestring (date-time)

      If present, when this access expires. This field is always provided on output.

    ttl

    • ttlstring (duration)

      Input only. The TTL for this resource.

  • 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}

• nextPageTokenstring

  A token, which can be sent as page_token to retrieve the next page.

• totalSizeinteger (int32)

  The total number of entitlements that match the request.

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