> ## 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 department 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/departments/{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/departments/{id}: get: tags: - Departments summary: Get description: >- Returns a department by its global id. Requires the `https://devx.{environment}.oleria.io/read` scope. operationId: GetDepartment parameters: - name: id in: path description: Global id of the department. required: true schema: type: string responses: '200': description: The department. content: application/json: schema: $ref: '#/components/schemas/Oleria_Department' '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_Department: type: object description: > An Oleria Department object represents a business department or organizational unit associated with employee records and organizational hierarchy in an enterprise HR system, identity provider, or directory service allOf: - $ref: '#/components/schemas/Department' - $ref: '#/components/schemas/Oleria_DepartmentGlobalIdentifiers' - $ref: '#/components/schemas/Oleria_DepartmentEnrichedInformation' - $ref: '#/components/schemas/Oleria_DepartmentAnalyticsInformation' - $ref: '#/components/schemas/Oleria_DepartmentSystemOfRecordInformation' - required: - oleriaObjectMetadata type: object properties: oleriaObjectMetadata: $ref: '#/components/schemas/Oleria_ObjectMetadata' Department: required: - id - name - objectMetadata type: object properties: authorizedLocations: $ref: '#/components/schemas/AuthorizedLocationPolicy' companyCode: type: string example: E39284 createdDate: type: string description: | The date the _Department_ object was created format: date-time example: '2024-05-02T03:17:34.948Z' id: $ref: '#/components/schemas/LocallyUniqueDepartmentId' lastModifiedDate: type: string description: | The date the _Department object was last modified format: date-time example: '2024-05-02T03:17:34.948Z' name: type: string example: Engineering objectDirectoryContainerFederation: $ref: '#/components/schemas/EntityIdentifierFederationInformation' objectDirectoryContainerId: $ref: '#/components/schemas/LocallyUniqueObjectDirectoryId' objectMetadata: $ref: '#/components/schemas/ObjectMetadata' type: type: string description: > The type for the _Department_ object allowing it to represent different types of organizational units (this can be used as a display name) example: Division, Business Unit description: Business department or division Oleria_DepartmentGlobalIdentifiers: required: - globalId type: object properties: globalAuthorizedLocations: $ref: '#/components/schemas/AuthorizedLocationPolicy' globalId: type: string globalObjectDirectoryContainerId: type: string description: > Global identifiers translated from Department local identifiers to be composed on Oleria Department Oleria_DepartmentEnrichedInformation: type: object description: > Enriched information derived from a combination of Department data, additional identity signals Oleria_DepartmentAnalyticsInformation: type: object description: > Analytics information calculated from identity security graph and added to the department Oleria_DepartmentSystemOfRecordInformation: type: object properties: sorPrimaryStewardEmail: type: string description: > System of Record information associated with a department 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. LocallyUniqueDepartmentId: type: string description: > An identifier for a [Department](#/components/schemas/Department) object 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 id so connections to the object are robust to metadata changes and other relevant operations. example: A34938434 EntityIdentifierFederationInformation: type: object required: - isFederated properties: authenticationKey: type: string isFederated: type: boolean description: | Federation information used when specifying an _EntityIdentifier_ 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 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. ````