> ## 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. # List > Returns a page of the subjects `requesterEmail` can request access to, each with the config that governs it and the reviewers their request would go to. Applications are limited to those federated by an identity provider the person belongs to. Pass `pageToken` from the previous response's `nextPageToken` to fetch the next page, and keep requesting pages until the response has no `nextPageToken`. 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 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: get: tags: - Requestable subjects summary: List description: >- Returns a page of the subjects `requesterEmail` can request access to, each with the config that governs it and the reviewers their request would go to. Applications are limited to those federated by an identity provider the person belongs to. Pass `pageToken` from the previous response's `nextPageToken` to fetch the next page, and keep requesting pages until the response has no `nextPageToken`. Requires the `https://devx.{environment}.oleria.io/read` scope. operationId: ListRequestableSubjects parameters: - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/subjectType' - $ref: '#/components/parameters/requesterEmail' - name: applicationId in: query description: >- Only return the requestable subject for this application, identified by its global id. schema: type: string responses: '200': description: A page of requestable subjects. content: application/json: schema: $ref: '#/components/schemas/RequestableList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - oauth2: - https://devx.{environment}.oleria.io/read components: parameters: pageSize: name: pageSize in: query description: Maximum items per page. schema: type: integer format: int32 default: 50 minimum: 1 maximum: 200 pageToken: name: pageToken in: query description: >- Opaque page token from the previous response's `nextPageToken`. Omit it for the first page; pass it back exactly as received. Do not parse or construct it. schema: type: string subjectType: name: subjectType in: query description: Only return results for this kind of subject. schema: $ref: '#/components/schemas/SubjectType' 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: RequestableList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Requestable' nextPageToken: $ref: '#/components/schemas/NextPageToken' totalCount: $ref: '#/components/schemas/TotalCount' SubjectType: type: string description: The kind of thing access is requested to. enum: - Application - CustomAction - DirectIntegration 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' NextPageToken: type: string description: >- Opaque token for the next page; pass it back as `pageToken`. Absent when no more results remain. Do not parse or construct it. TotalCount: type: integer description: Total number of results across every page. 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. 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' 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' 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. 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.