> ## 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 requestable subject by the id of the config that governs it, as `requesterEmail` would see it. Requires the `https://devx.{environment}.oleria.io/read` scope. ## OpenAPI ````yaml /developer-docs/api-reference/access-requests-openapi-schema-1.0.0.yaml get /v1/requestable-subjects/{id} openapi: 3.0.3 info: title: Oleria Access Requests API version: 1.0.0 description: >- REST API for Oleria access requests: submit a request for access on behalf of a person, follow it through its approval chain, and cancel it before it is decided. Requestable subjects list what a person can request and the config id to request it with. A change that is a state transition rather than an edit is a method on the request, such as `POST /v1/access-requests/{id}/cancel`. 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/requestable-subjects/{id}: get: tags: - Requestable subjects summary: Get description: >- Returns a requestable subject by the id of the config that governs it, as `requesterEmail` would see it. Requires the `https://devx.{environment}.oleria.io/read` scope. operationId: GetRequestableSubject parameters: - name: id in: path description: Id of the access request config that makes the subject requestable. required: true schema: type: string format: uuid - $ref: '#/components/parameters/requesterEmail' responses: '200': description: The requestable subject. content: application/json: schema: $ref: '#/components/schemas/Requestable' '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: parameters: requesterEmail: name: requesterEmail in: query description: >- Email address of the person the operation acts for. An API key has no person of its own, so requester operations name one. required: true schema: type: string format: email schemas: Requestable: type: object description: >- A subject people can request, with the config that governs it and who would review the request. required: - id - configuration - reviewers - subject properties: application: $ref: '#/components/schemas/Application' configuration: $ref: '#/components/schemas/AccessRequestConfig' id: type: string format: uuid description: Id of the config that makes the subject requestable. reviewers: type: array items: $ref: '#/components/schemas/UserReference' subject: $ref: '#/components/schemas/RequestableSubject' Application: type: object description: >- The application an application subject grants access to. Null for other subjects. nullable: true required: - id - idpApplicationInstanceId - idpApplicationInstanceName - idpApplicationName - peerGroupRating - sourceId properties: applicationInstanceType: type: string nullable: true catalogKey: type: string nullable: true id: type: string description: Global id of the application. idpApplicationInstanceId: type: string idpApplicationInstanceName: type: string idpApplicationName: type: string name: type: string nullable: true peerGroupMetrics: $ref: '#/components/schemas/PeerGroupMetrics' peerGroupPercentage: type: integer nullable: true peerGroupRating: $ref: '#/components/schemas/PeerGroupRating' sourceId: type: string AccessRequestConfig: type: object description: What makes one subject requestable, and how requests for it are handled. required: - id - subject - expiryConfig - notifyApprovers - requireJustification - createdAt - createdBy - updatedAt - updatedBy properties: actionType: $ref: '#/components/schemas/ProvisioningActionType' createdAt: type: string format: date-time createdBy: $ref: '#/components/schemas/Actor' expiryConfig: $ref: '#/components/schemas/ExpiryConfig' id: type: string format: uuid description: Id of this version of the config. An update returns a new id. isRequestable: type: boolean description: Whether people can currently request this subject. nullable: true isValidAppConfig: type: boolean description: >- Whether the application the config refers to still exists. Null when not evaluated. nullable: true notifyApprovers: $ref: '#/components/schemas/NotifyApprovers' requireJustification: type: boolean description: Whether a requester must give a justification. subject: $ref: '#/components/schemas/RequestableSubject' updatedAt: type: string format: date-time updatedBy: $ref: '#/components/schemas/Actor' UserReference: type: object description: A person, by name and email. required: - email - name properties: email: type: string name: type: string RequestableSubject: type: object description: >- The thing a config governs. `type` says which of `application`, `customAction` or `directIntegration` is set. required: - displayName - id - type properties: application: $ref: '#/components/schemas/ApplicationSubject' customAction: $ref: '#/components/schemas/CustomActionSubject' description: type: string nullable: true directIntegration: $ref: '#/components/schemas/DirectIntegrationConfig' displayName: type: string id: type: string description: >- Stable id of the subject. The application's global id, the custom action's webhook or manual action id, or the integration id. type: $ref: '#/components/schemas/SubjectType' 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. PeerGroupMetrics: type: object description: >- How many of the requester's peers hold this access, now and over the last 30 and 90 days. A null window has no data yet, which is not the same as zero. nullable: true properties: current: $ref: '#/components/schemas/PeerGroupWindow' past30Days: $ref: '#/components/schemas/PeerGroupWindow' past90Days: $ref: '#/components/schemas/PeerGroupWindow' PeerGroupRating: type: string enum: - High - Low - Medium - Unavailable ProvisioningActionType: type: string description: >- How approved access is provisioned. `CustomWebhook` and `Manual` apply only to custom actions. Defaults to `Waf`. default: Waf enum: - CustomWebhook - Manual - Waf Actor: type: object description: The person who made a change. required: - id - email properties: email: type: string id: type: string name: type: string nullable: true ExpiryConfig: type: object description: How long a request may wait for a decision before it expires. required: - durationInMinutes properties: durationInMinutes: type: integer NotifyApprovers: type: object description: Channels approvers are notified on. required: - email - slack properties: email: type: boolean slack: type: boolean ApplicationSubject: type: object required: - applicationId - groupAssignmentConfigs properties: applicationId: type: string description: Global id of the application. groupAssignmentConfigs: type: array description: >- The groups a requester can choose between. Provisioning adds the requester to the chosen group. items: $ref: '#/components/schemas/GroupAssignmentConfig' CustomActionSubject: type: object description: Exactly one of `webhookAction` or `manualAction` is set. properties: manualAction: $ref: '#/components/schemas/ManualActionConfig' webhookAction: $ref: '#/components/schemas/WebhookActionConfig' DirectIntegrationConfig: type: object required: - integrationId - selectableGroups - selectableRoles properties: integrationCatalogKey: type: string nullable: true integrationId: type: string selectableGroups: type: array items: $ref: '#/components/schemas/DirectIntegrationSelectableConfig' selectableRoles: type: array items: $ref: '#/components/schemas/DirectIntegrationSelectableConfig' SubjectType: type: string description: The kind of thing access is requested to. enum: - Application - CustomAction - DirectIntegration PeerGroupWindow: type: object nullable: true properties: percent: type: integer nullable: true rating: $ref: '#/components/schemas/PeerGroupRating' GroupAssignmentConfig: description: One group a requester of an application can ask to be added to. allOf: - $ref: '#/components/schemas/AccessDurationSettings' - type: object required: - id - groupName - groupType - oleriaGroupId properties: approvalChainId: type: string description: >- `chainId` of the approval chain that decides requests for this group. nullable: true displayName: type: string nullable: true groupId: type: string nullable: true groupName: type: string groupType: type: string id: type: string format: uuid description: >- Id of this group assignment. Pass it as `selectedGroupAssignmentConfigId` when creating a request. isValidGroupConfig: type: boolean description: Whether the group still exists. Null when not evaluated. nullable: true oleriaGroupId: type: string description: Global id of the group. peerGroupMetrics: $ref: '#/components/schemas/PeerGroupMetrics' ManualActionConfig: description: A custom action an administrator carries out outside Oleria. nullable: true allOf: - $ref: '#/components/schemas/ManualActionConfigInput' - type: object required: - id - createdAt - createdBy - updatedAt - updatedBy properties: createdAt: type: string format: date-time createdBy: $ref: '#/components/schemas/Actor' id: type: string format: uuid description: Id of the manual action. Identifies the custom action subject. updatedAt: type: string format: date-time updatedBy: $ref: '#/components/schemas/Actor' WebhookActionConfig: description: A custom action Oleria carries out by calling a webhook. nullable: true allOf: - $ref: '#/components/schemas/WebhookActionConfigInput' - type: object required: - id - createdAt - createdBy - updatedAt - updatedBy properties: createdAt: type: string format: date-time createdBy: $ref: '#/components/schemas/Actor' id: type: string format: uuid description: Id of the webhook action. Identifies the custom action subject. peerGroupMetrics: $ref: '#/components/schemas/PeerGroupMetrics' updatedAt: type: string format: date-time updatedBy: $ref: '#/components/schemas/Actor' DirectIntegrationSelectableConfig: description: A group or role of a direct integration that people can request. allOf: - $ref: '#/components/schemas/AccessDurationSettings' - type: object required: - id - selectableId - selectableType properties: approvalChainId: type: string description: >- `chainId` of the approval chain that decides requests for this option. nullable: true displayName: type: string nullable: true id: type: string format: uuid description: >- Id of this option. Pass it as `selectedDirectIntegrationGroupId` or `selectedDirectIntegrationRoleId` when creating a request. selectableId: type: string description: Id of the group or role in the integration. selectableType: type: string enum: - Group - Role AccessDurationSettings: type: object description: >- How long access granted through this option lasts, and how long a requester may ask for. required: - accessDurationType properties: accessDurationMinutes: type: integer description: >- Default duration in minutes. Only set when `accessDurationType` is `Custom`. nullable: true accessDurationType: $ref: '#/components/schemas/DurationType' accessDurationUnit: $ref: '#/components/schemas/DurationUnit' maxAccessDurationMinutes: type: integer description: >- Longest duration in minutes a requester may ask for. Only set when `accessDurationType` is `Custom`. nullable: true ManualActionConfigInput: allOf: - $ref: '#/components/schemas/AccessDurationSettings' - type: object required: - name - notifyEmail - notifySlack - notifyTeams - recipients properties: approvalChainId: type: string nullable: true description: type: string nullable: true name: type: string notifyEmail: type: boolean notifySlack: type: boolean notifyTeams: type: boolean provisioningRunbookLink: type: string description: >- Link to instructions for the administrator carrying out the action. Never shown to the requester. At least one of the link and text is required. nullable: true provisioningRunbookText: type: string description: >- Instructions for the administrator carrying out the action. Never shown to the requester. nullable: true recipients: $ref: '#/components/schemas/ManualActionRecipients' revokeRunbookLink: type: string nullable: true revokeRunbookText: type: string nullable: true WebhookActionConfigInput: allOf: - $ref: '#/components/schemas/AccessDurationSettings' - type: object required: - name - parameterContract - staticParameters - webhookId properties: approvalChainId: type: string nullable: true description: type: string nullable: true name: type: string parameterContract: type: array description: Fields the requester fills in. items: $ref: '#/components/schemas/ContractField' staticParameters: type: array description: Constants an administrator sets, sent on every call. items: $ref: '#/components/schemas/StaticParameter' webhookId: type: string format: uuid DurationType: type: string enum: - Custom - Permanent DurationUnit: type: string description: The unit a duration is shown in. Durations are always sent in minutes. nullable: true enum: - Days - Hours ManualActionRecipients: type: object description: Who is told to carry out the action, per channel. properties: email: type: array items: type: string slack: type: array items: type: string teams: type: array items: type: string ContractField: type: object description: >- A parameter a requester fills in when requesting a webhook custom action. required: - index - name - required - type properties: contributesToPeerGroup: type: boolean description: >- Whether the value is part of how peer group coverage is computed. Defaults to false. description: type: string nullable: true id: type: string format: uuid description: >- Id of the field. Set by Oleria; omit it when creating or updating a config. readOnly: true index: type: integer name: type: string optionsValue: type: array description: The allowed values of a `Choice` field. nullable: true items: type: string required: type: boolean type: type: string enum: - Boolean - Choice - Number - String StaticParameter: type: object description: A constant always sent to the webhook. required: - name - value properties: name: type: string value: type: string responses: BadRequest: description: >- The request was malformed, for example an invalid cursor, page size or body. 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/read: Read access requests and requestable subjects. https://devx.{environment}.oleria.io/write: Submit and cancel access requests. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.