> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Get > Returns a role by its global id. Requires the `https://devx.{environment}.oleria.io/read` scope. ## OpenAPI ````yaml /developer-docs/api-reference/oleria-public-api-1.0.0.yaml get /v1/roles/{id} openapi: 3.0.3 info: title: Oleria Public API version: 1.0.0 description: >- REST API for Oleria's identity and access data. Each resource is a collection exposing list and get operations; responses return the complete object. Where Oleria can change what it reports, the change is a method on the same resource: disabling an account is `POST /v1/accounts/{id}/disable`, and membership is a sub-resource asserted with `PUT` and removed with `DELETE`. Those changes are applied in the source application asynchronously: each returns a job under `/v1/action-jobs` that reports the outcome for every target it affected, and whether Oleria's own data reflects it yet. Authenticate with OAuth 2.0 client credentials and send the access token as `Authorization: Bearer `. servers: - url: https://devx.{environment}.oleria.io description: Oleria API server. variables: environment: default: prod description: >- Your Oleria deployment, for example `acme` for `https://devx.acme.oleria.io`. Substitute it in the OAuth scope names as well, since OpenAPI applies a server variable to the URL only and the scopes are published with the placeholder still in them. security: [] paths: /v1/roles/{id}: get: tags: - Roles summary: Get description: >- Returns a role by its global id. Requires the `https://devx.{environment}.oleria.io/read` scope. operationId: GetRole parameters: - name: id in: path description: Global id of the role. required: true schema: type: string responses: '200': description: The role. content: application/json: schema: $ref: '#/components/schemas/Oleria_Role' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - oauth2: - https://devx.{environment}.oleria.io/read components: schemas: Oleria_Role: type: object description: > An Oleria Role object represents a security role that can be assigned to accounts and groups in an application and is typically used in role-based access control (RBAC) systems to group and represents one or more sets of permissions that grant access to resources. Note this is a different representation than Oleria AccountRole which is purely used to represent entitlement descriptions and is typically a unit of entitlement assignment brokered between and IDP and an enterprise application allOf: - $ref: '#/components/schemas/Role' - $ref: '#/components/schemas/Oleria_RoleGlobalIdentifiers' - $ref: '#/components/schemas/Oleria_RoleEnrichedInformation' - $ref: '#/components/schemas/Oleria_RoleAnalyticsInformation' - $ref: '#/components/schemas/Oleria_RoleSystemOfRecordInformation' - required: - oleriaObjectMetadata type: object properties: oleriaObjectMetadata: $ref: '#/components/schemas/Oleria_ObjectMetadata' Role: required: - applicationRoleType - id - isCustom - name - objectMetadata - type type: object properties: applicationRoleType: type: string description: >- This is an application-specific string indicating the type of role being represented by the Role object. Typically this is the information used to derive the RoleType specified in the Role.type field or something related to the source of the Role specified in Role.sourceTag authorizedLocations: $ref: '#/components/schemas/AuthorizedLocationPolicy' createdBy: $ref: '#/components/schemas/LocallyUniqueAccountId' createdByFederation: $ref: '#/components/schemas/EntityIdentifierFederationInformation' createdDate: type: string format: date-time example: '2024-05-02T03:17:34.948Z' description: type: string description: >- The description of the role indicating its purpose in grouping permissions and granting access to resources example: oleria Repos Writers id: $ref: '#/components/schemas/LocallyUniqueRoleId' isCustom: type: boolean description: >- Is this a custom-defined role? If true, then the Role.type equals Custom example: false lastModifiedBy: $ref: '#/components/schemas/LocallyUniqueAccountId' lastModifiedByFederation: $ref: '#/components/schemas/EntityIdentifierFederationInformation' lastModifiedDate: type: string description: The date the role was last modified format: date-time example: '2024-05-02T03:17:34.948Z' name: minLength: 1 type: string description: >- The name of the role which is typically informative of the role's purpose for granting access to resources (see also description) example: oleria Repo Maintainers objectDirectoryContainerFederation: $ref: '#/components/schemas/EntityIdentifierFederationInformation' objectDirectoryContainerId: $ref: '#/components/schemas/LocallyUniqueObjectDirectoryId' objectMetadata: $ref: '#/components/schemas/ObjectMetadata' sourceTag: type: string description: >- An application-specific tag representing the role information data source example: oleria type: $ref: '#/components/schemas/RoleType' description: >- A Role object represents a security role that can be assigned to accounts and groups in an application and is typically used in role-based access control (RBAC) systems to group and represents one or more sets of permissions that grant access to resources Oleria_RoleGlobalIdentifiers: required: - globalId type: object properties: globalAuthorizedLocations: $ref: '#/components/schemas/AuthorizedLocationPolicy' globalCreatedBy: type: string globalId: type: string globalLastModifiedBy: type: string globalObjectDirectoryContainerId: type: string description: > Global identifiers translated from Role local identifiers to be composed on Oleria Role Oleria_RoleEnrichedInformation: type: object description: > Enriched information derived from a combination of Role data, additional identity signals Oleria_RoleAnalyticsInformation: type: object properties: analyticsAccessToResourceInstancesCount: type: integer nullable: true description: > Cached count of resource instances this role can access, including nested (Contains) descendants. Values above 1000 may be approximate. Note that access to resource (vs. resource instance) is deprecated. format: int64 analyticsActiveMemberCount: type: integer nullable: true format: int32 analyticsAssignedApplicationCount: type: integer nullable: true format: int32 analyticsAssignedRoleCount: type: integer nullable: true format: int32 analyticsAssignedUserGroupCount: type: integer nullable: true format: int32 analyticsInactiveMemberCount: type: integer nullable: true format: int32 analyticsMemberAccountsCount: type: integer nullable: true format: int32 analyticsMemberCount: type: integer nullable: true format: int32 analyticsOwners: type: array items: type: string description: > Analytics information calculated from identity security graph and added to the role Oleria_RoleSystemOfRecordInformation: type: object properties: sorPrimaryStewardEmail: type: string description: > System of Record information associated with a role and managed in Oleria Oleria_ObjectMetadata: type: object properties: enrichmentVersion: type: string generatedTime: type: string format: date-time description: > object metadata supersets object metadata with platform enrichment provenance — the enrichment version and the time the record was generated ErrorResponse: type: object description: >- Error envelope. `code` is a stable machine-readable identifier; `message` is human-readable. required: - code - message properties: code: type: string description: Stable, machine-readable error code (SCREAMING_SNAKE_CASE). example: NOT_FOUND details: type: object description: Optional free-form context for debugging. additionalProperties: true message: type: string description: Human-readable description of the error. example: No resource with the given id. AuthorizedLocationPolicy: type: object required: - isInherited properties: isInherited: type: boolean description: > When set to true this indicates that the location policy is inherited from another object, otherwise the location policy is directly specified policy: oneOf: - $ref: '#/components/schemas/AuthorizedEntityLocationPolicy' - $ref: '#/components/schemas/AuthorizedInheritedLocationPolicy' description: > _AuthorizedLocationPolicy_ is used to specify locations authorized for use by accounts, groups, roles, employees, departments, etc. LocallyUniqueAccountId: type: string description: > An identifier (unique to integrated application) for an [Account](#/components/schemas/Account) object represented in the Oleria system. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. It is important for this identifier to be based on an underlying persistent and reusable application or identity provider id so connections to the object are robust to metadata changes and other relevant operations example: >- user:U_kgDOB7P6Rg (GitHub based on node identifier), 838439349399 (Google Workspace based on user id), user:wiz-inc-4db1c46901 (GitHub based on app slug) EntityIdentifierFederationInformation: type: object required: - isFederated properties: authenticationKey: type: string isFederated: type: boolean description: | Federation information used when specifying an _EntityIdentifier_ LocallyUniqueRoleId: type: string description: > An identifier (unique to the integrated application) for a [Role](#/components/schemas/Role) object represented in the Oleria system. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. It is important for this identifier to be based on an underlying persistent and reusable application or identity provider id so connections to the object are robust to metadata changes and other relevant operations example: 0PSHu000003fo6tOAA (Salesforce based on permission set ids) LocallyUniqueObjectDirectoryId: type: string description: > An identifier (unique to the integrated application) for a [ObjectDirectory](#/components/schemas/ObjectDirectory) object represented in the Oleria system. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. It is important for this identifier to be based on an underlying persistent and reusable application or identity provider id so connections to the object are robust to metadata changes and other relevant operations example: >- repo:R_kgDOLL0doQ (GitHub based on repository node identifier), 1BUxdX4M-H7X8GKRgTjprJS8fjY_Ij1giE82lQlny2kc (Google Drive based on file id) ObjectMetadata: required: - ApplicationInstanceId - GeneratedTime type: object properties: ApplicationInstanceId: type: string GeneratedTime: type: string format: date-time Profile: $ref: '#/components/schemas/SchemaProfile' ObjectOrRelationshipType: type: string description: > The _ObjectMetadata_ structure defines metadata that applies to every object and relationship, and is usually managed by the system that receives the data RoleType: type: string description: > The type of the role used to group permissions in role based access control (RBAC) systems and thus give access to particular resources are described as follows: 1. _Custom_ roles are created by administrators or users (with sufficient privilege) to represent a custom set of permissions that grant unique access to application resources 2. _Modeled_ roles are roles created to model access to resources in the application, but are not "physically" represented in the application's schema. An example of modeled roles are each repository's access roles in GitHub. These are represented as modeled roles in Oleria because each repository evaluates roie membership and access with its own virtual instance of the standard read, write, triage, maintain, and admin GitHub roles. 3. _Standard_ roles are the documented or system installed application roles described by the application and represented in the Oleria schema example: Standard enum: - Custom - Modeled - Standard AuthorizedEntityLocationPolicy: type: object required: - allowAll properties: allowAll: type: boolean description: | When set to true this indicates that all locations are authorized authorizedLocations: type: array description: > These are the locations authorized for use by the entity that has this policy. If none are specified then no locations are allowed. If any are specified and it is desirable for the _assignedLocations_ to be authorized, then they must be explicitly included in the array items: $ref: '#/components/schemas/LocationSpecification' description: > _AuthorizedEntityLocationPolicy_ is used to specify locations authorized for use by the specific entity that it is attached to AuthorizedInheritedLocationPolicy: type: object properties: sourceObjectType: $ref: '#/components/schemas/ObjectType' sourceObjectId: $ref: '#/components/schemas/LocallyUniqueId' description: > _AuthorizedInheritedLocationPolicy_ is used to specify an object that is the source for the location authorization data used by the specific entity the _AuthorizedInheritedLocationPolicy_ is attached to SchemaProfile: type: string enum: - Account - Membership - Governance - Risk - Access - Detection LocationSpecification: type: object properties: type: $ref: '#/components/schemas/LocationSpecificationType' typeSpecificData: oneOf: - $ref: '#/components/schemas/NetworkLocationSpecification' - $ref: '#/components/schemas/PhysicalLocationSpecification' ObjectType: type: string description: >- The enumerated list of all Oleria objects used to describe and manage any customer application's identity security. The definition of each object describes its usage example: Account enum: - Account - AccountRole - Activity - AssignedApplication - Authenticator - AuthenticatorEnrollment - Department - DirectoryProvider - Employee - IntegratedApplication - None - ObjectDirectory - PermissionSet - Person - ResourceClass - ResourceInstance - RiskDefinition - RiskViolation - Role - UserGroup LocallyUniqueId: minLength: 1 type: string description: > An identifier (unique to the integrated or assigned application) of any object or entity represented in the Oleria system as well as any relationship or connection among entities when they are represented in Oleria. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. The full list of Oleria objects or entities is defined by the object-type enumeration, and the full list of relationships or connections is defined by the relationship-type enumeration LocationSpecificationType: type: string enum: - Network - Physical NetworkLocationSpecification: type: object properties: ipAddressExclusions: type: array items: type: string ipAddressInclusions: type: array items: type: string name: type: string supplementaryInformation: $ref: '#/components/schemas/SupplementaryLocationInformation' description: > Specify a network location or zone with a name and a list of IP addresses or ranges (including in CIDR notation) PhysicalLocationSpecification: type: object properties: addressedObjectIdentifier: $ref: '#/components/schemas/AddressedObjectIdentifier' countryLevelInformation: $ref: '#/components/schemas/CountryLevelInformation' locality: $ref: '#/components/schemas/Locality' postcode: type: string description: | Postal code or ZIP code example: '98112' supplementaryInformation: $ref: '#/components/schemas/SupplementaryLocationInformation' description: > A subset of the ISO 19160-4:2023 delivery point specification. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 SupplementaryLocationInformation: type: object properties: geoLocation: $ref: '#/components/schemas/GeoLocation' additionalLocationMetadata: type: array items: $ref: '#/components/schemas/MetadataItem' AddressedObjectIdentifier: type: object properties: building: type: string description: > Element identifying the number or name and type of the location edifice or construction example: The Madrona Refuge Building door: type: string description: | Element identifying the apartment, room, or office example: Suite 301 premisesIdentifier: type: string description: > Element designating the area or the object on an area associated with the location example: 1126 34th Avenue description: > Subset of an ISO 19160-4:2023 construct identifying a specific addess within a [Locality](#/components/schemas/Locality). For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 CountryLevelInformation: type: object properties: countryCode: type: string description: > Element designating the ISO 3166-1 A-2 country code for the country, territory or area of geopolitical interest example: US countryName: type: string description: > Element designating the country, dependency, or area of geopolitical interest example: United States multiCountryRegion: type: string description: > Element indicating a region in which the country, territory, or area of geopolitical interest is located and by which it is potentially more effectively recognized example: North America description: > Subset of ISO 19160-4:2023 country level information. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 Locality: type: object properties: district: type: string description: > Element indicating the name of the area within or adjacent to the specified town example: Madrona (neighborhood in Seattle) region: type: string description: > Element specifying the geographic or administrative area of the country in which the town is situated example: Washington town: type: string description: > Element indicating the name of the populated place associated with the [LocationSpecification](#/components/schemas/LocationSpecification) in which this _Locality_ is being referenced example: Seattle description: > Subset of ISO 19160-4:2023 locality information identifying the geographical area. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 GeoLocation: type: object required: - latitude - longtitude properties: latitude: type: number longtitude: type: number description: Latitude and longtitude specification for a location MetadataItem: type: object properties: id: type: string name: type: string namespace: type: string type: $ref: '#/components/schemas/MetadataValueType' value: type: object MetadataValueType: type: string enum: - array_boolean - array_float32 - array_float64 - array_int32 - array_int64 - array_string - boolean - float32 - float64 - int32 - int64 - oleria_global_id - oleria_local_id - pem - property_bag - rfc3339_date - string responses: BadRequest: description: The request was malformed, for example an invalid cursor or page size. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: BAD_REQUEST message: The request was malformed. Unauthorized: description: Missing or invalid authentication token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: UNAUTHORIZED message: Missing or invalid authentication token. Forbidden: description: The token lacks the scope required for this resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: FORBIDDEN message: The token lacks the required scope. NotFound: description: No resource exists with the given id. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: NOT_FOUND message: No resource with the given id. TooManyRequests: description: Rate limit exceeded. Retry after the interval in the Retry-After header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: TOO_MANY_REQUESTS message: Rate limit exceeded. Retry after the specified interval. InternalError: description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: INTERNAL_ERROR message: An unexpected error occurred. securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client-credentials flow. Request an access token from the token endpoint and send it as `Authorization: Bearer `. flows: clientCredentials: tokenUrl: https://auth.prod.oleria.io/oauth/token scopes: https://devx.{environment}.oleria.io/delete: Irreversibly destroy an object in the source system. https://devx.{environment}.oleria.io/read: Read identity and access data, and the jobs that change it. https://devx.{environment}.oleria.io/write: >- Make reversible changes: grant, enable, assign, revoke and remove access. ````