> ## Documentation Index > Fetch the complete documentation index at: https://docs.plerion.com/llms.txt > Use this file to discover all available pages before exploring further. # List AWS access grants > Retrieve the tenant's active access grants, ordered by `firstObservedAt` descending. Supports filtering by origin, trust status, scope, resource and review state, with cursor-based pagination. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/tenant/aws/access-grants openapi: 3.1.0 info: title: Plerion API Documentation version: v1 termsOfService: https://www.plerion.com/terms-and-conditions contact: name: Plerion Pty Ltd url: https://www.plerion.com/contact-us email: support@plerion.com license: name: Plerion Use License url: https://www.plerion.com/terms-and-conditions description: |-
The Plerion API allows you to programmatically interact with Plerion.
Base URL: https://{region}.api.plerion.com servers: - url: https://{region}.api.plerion.com description: Production API server - Select your preferred region variables: region: default: au enum: - au - sg1 - in1 - us1 security: [] tags: - name: QUICK_START x-displayName: Quick Start description: >- This section describes how to quickly get started with the Plerion API using curl. For a more detailed guide, see the sections below.

Getting started with curl

1. Install curl if it isn't already installed on your machine. To check if curl is installed, execute curl --version in the command line. If the output is information about the version of curl, it is installed. If you get a message similar to command not found: curl, you need to download and install curl. For more information, see the curl project download page.


2. Create a Tenant API key accessing Tenant API Keys Dashboard.
Warning: Treat your API key like a password. Do not store it as plain text or expose it in any code base.


3. Use the curl command to make your request. Pass your API key in an Authorization header. Replace {PLERION_API_KEY} with your API key. 

        export PLERION_API_URL=au.api.plerion.com
        export PLERION_API_KEY={PLERION_API_KEY}

        curl --request GET \\
        --url "https://$PLERION_API_URL/v1/tenant/findings" \\
        --header "Authorization: Bearer $PLERION_API_KEY"

- name: Overview x-displayName: Overview description: >- Plerion API uses API keys to authenticate requests. You can view and manage your API keys in the Plerion app Tenant API Keys Dashboard. API responses are JSON-encoded.

Authentication

To authenticate to Plerion API send the API Key using bearer auth in the Authorization header 


      Authorization: Bearer $PLERION_API_KEY
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.


Errors

Plerion uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Plerion's servers. Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. Detailed description for the status code can be found in th Response Status Codes section.


Response Status Codes

The Plerion API endpoints return the following HTTP response status codes.
Status CodeDefinitionDescription
200 OK The request has succeeded.
201 Created The request has been fulfilled and resulted in a new resource being created.
204 No Content The server has fulfilled the request but does not need to return an entity-body.
400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized The request requires user authentication. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not fix the issue and the request SHOULD NOT be repeated.
404 Not Found The server has not found anything matching the Request-URI.
405 Method Not Allowed The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
412 Precondition Failed The resource changed after the version supplied in the If-Match header. Read the resource again and retry the request with the version returned.
429 Too Many Requests Too many requests occurred during the allotted time period and rate limiting was applied.
500 Internal Server Error The request did not complete due to an internal error on the server side. The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
- name: Findings x-displayName: Findings description: >- Findings are the results of the Plerion Detection Engine (PDE) Detection reporting a finding and rating the severity of the finding as it relates to best practices or a relevant compliance standard. Plerion Findings enable customers to reduce the risk to their environments by continuously highlighting areas for improvement. - name: Vulnerabilities x-displayName: Vulnerabilities description: >- Vulnerabilities are known CVEs Plerion detects in the operating systems, packages and container images running in your cloud workloads. Each one carries the affected package and version, its severity, its Exploit Prediction Scoring System (EPSS) score from FIRST, and whether a public exploit or a known-exploited-vulnerability record exists, so remediation can be ordered by known exploitation rather than by CVSS score alone. Vulnerability exemptions record a CVE you have accepted or judged not applicable for a profile, with a reason, so it stops surfacing on later scans. - name: Profiles x-displayName: Profiles description: >- A profile holds the detection configuration Plerion applies to a set of integrations: which detections run, at what severity, and the exemptions that stop them reporting. Every tenant has a default profile, and it covers only the integrations that have not been given a profile of their own, so a change made against it does not reach an integration another profile already covers. List your profiles to see which integrations each one applies to before configuring anything, and to pick the profile IDs the detection exemption and vulnerability exemption endpoints take. - name: Detection exemptions x-displayName: Detection Exemptions description: >- A detection exemption stops one detection reporting findings against the assets it matches, on one profile. Match on the asset's name, its tags, or its region; on the principal for Cloud Detection and Response (CDR) detections; or on the API Gateway routes you have accepted. Exemptions are configured per detection rather than stored as records of their own, so there is no exemption ID and no endpoint for a single entry. You read the whole set for a detection, change it, and write it back, using the returned version as an `If-Match` header so a concurrent change is rejected rather than overwritten. Not every detection accepts exemptions, and of the ones that do, none accepts every type. The read reports both, and a write using an unsupported type is rejected rather than stored where it would never take effect. - name: Assets x-displayName: Assets description: >- Plerion Assets form the basis upon which all Plerion contextual security is reported. Every unique cloud resource on which Plerion collects information is classified as a single asset on the Plerion platform. A detailed asset view combines various sources of security, compliance, and risk-related metrics to empower customers to make high-impact decisions when evaluating a single asset in relation to their overall cloud environments. - name: Asset groups x-displayName: Asset Groups description: >- Asset Group is classifying assets into specific group based on the different criteria such as integration, asset tag, resource type and resource name. This helps users to manage, organize, and analyze their assets more efficiently. User can group assets based on the teams, projects, business units, environments, tech stack etc. - name: Custom checks x-displayName: Custom Checks description: >- Custom checks are customer-authored rego policies that Plerion evaluates against your collected assets, turning matches into findings. Manage them programmatically — create, list, read, update, and delete — so your checks live in code and ship through your pipeline. Dry-run a check against live assets to preview its findings before it goes live, without persisting any findings or moving compliance state. - name: Alerts x-displayName: Alerts description: >- The Plerion Risk Score (PRS) Engine has calculated Alerts that are the highest priority items based on the available information across Identity, Configuration, and Vulnerability Management. Alerts offer the highest value CONTEXT from across the Plerion Platform. Alerts are accompanied by a narrative to guide customers on the overall risk and the recommended remediation steps to take to improve, reduce, or eradicate the identified risk. - name: Integrations x-displayName: Integrations description: >- Integrations enable customers to connect their own cloud environments to the Plerion platform. Integrations allow for the collection of data from the integrated environment, e.g. Connecting Plerion to your cloud service provider will facilitate Plerion to collect, analyze, and prioritize the most significant risks across your cloud operating environments. - name: Tenant x-displayName: Tenant description: >- The Plerion platform caters for multi-tenancy. Multi-tenancy within the Plerion platform delivers isolation for the integrations supported by Plerion. Each Tenancy (Tenant) allows for multiple inbound or outbound integrations, like integrating with Cloud Service Providers (AWS, Azure, GCP), and their corresponding Audit log service (AWS: CloudTrail, Azure: AuditLog, GCP: Cloud Audit Log). - name: Custom dashboards x-displayName: Custom dashboards description: >- Custom dashboards are the reports built in the Plerion app's dashboard builder. List them to find the id a home dashboard preference points at. - name: Preferences x-displayName: Preferences description: >- The tenant default home dashboard. It is the dashboard a user lands on when neither they nor one of their user groups has chosen one. User and user group preferences are organization-level and live on the organization API. - name: Risks x-displayName: Risks description: >- In a cloud environment there are usually many hundreds or thousands of misconfigurations, but which of those pose a clear and present danger of a breach? That’s what the Plerion risk is about. - name: AWS integration x-displayName: AWS Integration description: >- In order to connect your AWS account to Plerion or update existing account, you will need,
  1. CloudFormation Template URL. Retrieve the template from Get CloudFormation template
  2. External Id of the tenant. Retrieve the External Id from Get the external id of the tenant
  3. Plerion AWS Account Id. The value will always be 588158338731
  4. Tenant Id. Identifies your tenant when the stack registers itself with Plerion. Retrieve the tenant Id from Get tenant details
  5. Plerion API URL. The host used by the API calls above. The value will always be au.api.plerion.com
  6. Select Capabilities. Select CSPM for CSPM only capability or ALL for both CSPM and CWPP capability.
  7. Select KMSKeyAccessMode. When CWPP is enabled, you can choose the KMS Key access mode to facilitate Plerion's access to keys for decrypting volumes, images, and lambda code. In the ALL_KEYS mode, Plerion is granted access to all KMS keys in the account. However, you have the option to restrict access to certain keys by applying the "PlerionAccess: Denied" tag. Alternatively, the SELECTED_KEYS mode allows Plerion access solely to the KMS keys that have been tagged with "PlerionAccess: Granted".
Passing the parameters to the CloudFormation template will create a new AWS integration or update existing integration.

Quick Start

Follow the guide to create a new AWS integration or update existing integration using curl command.
Note: Replace {$PLERION_API_KEY} with your API key.

Create a new AWS Integration

        export PLERION_API_URL=au.api.plerion.com
        export PLERION_API_KEY={$PLERION_API_KEY}
        export PLERION_AWS_ACCOUNT_ID=588158338731
        # Fetch the template URL
        export TEMPLATE_URL=$(curl -s GET  "https://$PLERION_API_URL/v1/tenant/cloudformation-templates?type=AWSAccount" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.templateURL')
        # Fetch the external ID
        export EXTERNAL_ID=$(curl -s -X GET  "https://$PLERION_API_URL/v1/tenant/external-id" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.externalId')
        # Fetch the tenant ID
        export TENANT_ID=$(curl -s -X GET  "https://$PLERION_API_URL/v1/tenant" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.tenantId')
        # Create the stack
        export PLERION_STACK_NAME=plerion-aws-integration
        aws cloudformation create-stack --stack-name $PLERION_STACK_NAME --template-url $TEMPLATE_URL --capabilities CAPABILITY_NAMED_IAM \
          --parameters ParameterKey=ExternalId,ParameterValue=$EXTERNAL_ID \
            ParameterKey=PlerionAccountId,ParameterValue=$PLERION_AWS_ACCOUNT_ID  \
            ParameterKey=TenantId,ParameterValue=$TENANT_ID \
            ParameterKey=Capabilities,ParameterValue=ALL \
            ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS"
        # Wait for the stack to complete
        aws cloudformation wait stack-create-complete --stack-name $PLERION_STACK_NAME


Update an existing AWS Integration

        export PLERION_API_URL=au.api.plerion.com
        export PLERION_API_KEY={$PLERION_API_KEY}
        export PLERION_AWS_ACCOUNT_ID=588158338731
        # Fetch the template URL
        export TEMPLATE_URL=$(curl -s GET  "https://$PLERION_API_URL/v1/tenant/cloudformation-templates?type=AWSAccount" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.templateURL')
        # Fetch the external ID
        export EXTERNAL_ID=$(curl -s -X GET  "https://$PLERION_API_URL/v1/tenant/external-id" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.externalId')
        # Fetch the tenant ID
        export TENANT_ID=$(curl -s -X GET  "https://$PLERION_API_URL/v1/tenant" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.tenantId')
        # Update an existing stack
        export PLERION_STACK_NAME=plerion-aws-integration
        aws cloudformation update-stack --stack-name $PLERION_STACK_NAME --template-url $TEMPLATE_URL --capabilities CAPABILITY_NAMED_IAM \
          --parameters ParameterKey=ExternalId,ParameterValue=$EXTERNAL_ID \
            ParameterKey=PlerionAccountId,ParameterValue=$PLERION_AWS_ACCOUNT_ID  \
            ParameterKey=TenantId,ParameterValue=$TENANT_ID \
            ParameterKey=Capabilities,ParameterValue=ALL \
            ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS"
        # Wait for the stack to complete
        aws cloudformation wait stack-update-complete --stack-name $PLERION_STACK_NAME
- name: Compliance frameworks x-displayName: Compliance Frameworks description: >- Compliance Frameworks help our customers meet their regulatory and compliance obligations, and reduce compliance risk, enabling them to achieve their strategic objectives. Plerion offers customers hundreds of prebuilt detections delivering continuous assurance against industry standards and best practices. - name: Well-Architected frameworks x-displayName: Well-Architected Frameworks description: >- The AWS Well-Architected Framework helps customers design secure, high-performing, resilient, and efficient cloud infrastructure. Plerion continuously assesses your environment against the AWS Well-Architected pillars, aligning your architecture with AWS best practices and accelerating improvement. - name: Code security x-displayName: Code Security description: >- Code security scans infrastructure-as-code before it reaches a cloud environment, so a misconfiguration is caught in the pull request rather than after deployment. Upload a Terraform, CloudFormation or Kubernetes archive to start a scan, then retrieve the findings it produced and any vulnerabilities detected in container images the templates reference. - name: Tenant usage x-displayName: Tenant Usage description: Plerion Usage information for the Tenant - name: Audit logs x-displayName: Audit Logs description: >- Audit logs provide a comprehensive trail of user activities and system operations within a tenant. These logs capture important events such as user logins, API calls, configuration changes, and other security-relevant activities. Audit logs help with compliance, security monitoring, and troubleshooting. - name: AWS access grants x-displayName: Access Grants description: >- An access grant records the access that one of your AWS resources gives to a single principal. Plerion derives grants from resource policies, IAM role trust policies, AWS Resource Access Manager shares and cross-account share attributes, capturing the principal, the actions allowed and any conditions attached. Use these endpoints to pull the inventory into your own audits or SIEM, and to record review decisions without signing in to Plerion. - name: Metrics x-displayName: Metrics description: >- The time series behind the Plerion dashboards, such as finding, asset, risk and alert counts, posture scores and Plerion unit consumption, queried by namespace and metric name over a period. - name: Workload scans x-displayName: Workload Scans description: >- Request a scan of one workload now, ahead of the schedule, and follow its status. paths: /v1/tenant/aws/access-grants: get: tags: - AWS access grants summary: List description: >- Retrieve the tenant's active access grants, ordered by `firstObservedAt` descending. Supports filtering by origin, trust status, scope, resource and review state, with cursor-based pagination. operationId: listTenantAccessGrants parameters: - $ref: '#/components/parameters/paramAuthHeader' - in: query name: grantOrigin description: >- Filter by whether the principal is outside your AWS organization or inside it. Accepts a single value. Available options: `external`, `internal` schema: type: string example: external - in: query name: trustStatuses description: >- Filter by trust status. Accepts a comma-separated list. Grants that have not been evaluated have no trust status and are excluded by this filter. Available options: `trusted`, `untrusted` schema: type: string example: trusted,untrusted - in: query name: grantScopes description: >- Filter by trust-boundary relationship. Accepts a comma-separated list. Available options: `cross-org`, `federated`, `public`, `same-account`, `same-org`, `aws-service` schema: type: string example: cross-org,public - in: query name: mechanisms description: >- Filter by the mechanism granting the access. Accepts a comma-separated list. Available options: `resource_policy`, `trust_policy`, `ram_share`, `attribute_share` schema: type: string example: resource_policy,trust_policy - in: query name: principalTypes description: >- Filter by what the principal is. Accepts a comma-separated list. Available options: `aws_account`, `aws_role`, `aws_user`, `public`, `conditional`, `aws_org`, `oidc`, `saml`, `cognito_identity`, `canonical_user`, `external_idp`, `aws_service`, `aws_support` schema: type: string example: aws_account,public - in: query name: resourceTypes description: >- Filter by the CloudFormation resource type of the granting resource. Accepts a comma-separated list. schema: type: string example: AWS::S3::Bucket,AWS::IAM::Role - in: query name: integrationIds description: Filter by integration IDs. Accepts a comma-separated list of UUIDs. schema: type: string example: 458511a1-9bc2-4fce-97a0-0e3139588e6e - in: query name: awsAccountIds description: >- Filter by the AWS account owning the granting resource. Accepts a comma-separated list of 12-digit account IDs. schema: type: string example: '111122223333' - in: query name: principalAccountIds description: >- Filter by the AWS account of the principal. Accepts a comma-separated list of 12-digit account IDs. schema: type: string example: '444455556666' - in: query name: assetName description: >- Filter to grants whose resource name or asset ID contains this value. Case-insensitive substring match, maximum 256 characters. schema: type: string maxLength: 256 example: acme-prod - in: query name: principal description: >- Filter to grants whose principal contains this value. Case-insensitive substring match, maximum 256 characters. schema: type: string maxLength: 256 example: '444455556666' - in: query name: search description: >- Filter to grants where the principal, resource name, principal name or asset ID contains this value. Case-insensitive substring match, maximum 256 characters. schema: type: string maxLength: 256 example: vendor - in: query name: ids description: >- Filter to specific grant IDs. Accepts a comma-separated list of UUIDs. Use this to re-fetch grants whose IDs you already hold. schema: type: string example: 0f9a1c3e-5b7d-4c21-9e8f-2a6b4d10c7f3 - in: query name: reviewDecisions description: >- Filter by recorded review decision. Accepts a comma-separated list of `keep`, `remove`, `review_later` and `trust_until_review`. Grants with no decision recorded are excluded, so this cannot be used to find unreviewed grants. schema: type: string example: keep,review_later - in: query name: grantee description: >- Filter to grants whose recorded grantee contains this value. Case-insensitive substring match, maximum 256 characters. schema: type: string maxLength: 256 example: platform-team - in: query name: nextReviewAtEnd description: >- Filter to grants due for review by this date. Inclusive upper bound on `nextReviewAt`; a grant with no next-review date set is not due and is excluded. schema: type: string format: date-time example: '2026-09-15T00:00:00.000Z' - in: query name: cursor description: >- Get the next page of access grants. Pass the `meta.cursor` value from the previous response. schema: type: string example: >- eyJmaXJzdE9ic2VydmVkQXQiOiIyMDI2LTAzLTAyVDIyOjA4OjAwLjAwMFoiLCJpZCI6IjZiMzFkODRhIn0= - in: query name: perPage description: >- Number of items per page, from 1 to 1000. Defaults to 100. A value above 1000 is rejected with a `400`. schema: type: integer minimum: 1 maximum: 1000 default: 100 example: 50 responses: '200': description: Access grants list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AccessGrant' meta: type: object properties: perPage: type: integer example: 25 total: description: >- Total matching grants. Returned on the first page only; `null` on cursor-fetched pages. type: - integer - 'null' example: 412 cursor: description: >- Pass back as `cursor` to fetch the next page. `null` on the last page. type: - string - 'null' example: >- eyJmaXJzdE9ic2VydmVkQXQiOiIyMDI2LTAzLTAyVDIyOjA4OjAwLjAwMFoiLCJpZCI6IjZiMzFkODRhIn0= '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' security: - APIKey: [] components: parameters: paramAuthHeader: name: Authorization in: header description: Bearer API Key. For example, "Bearer {Tenant API Key}" required: true schema: type: string schemas: AccessGrant: type: object properties: id: type: string example: 0f9a1c3e-5b7d-4c21-9e8f-2a6b4d10c7f3 organizationId: type: string example: dc16d897-7f52-4b73-be57-96c7c9a853da tenantId: type: string example: 42749bc1-c99b-4c2c-a081-a6cda9370081 integrationId: type: string example: 458511a1-9bc2-4fce-97a0-0e3139588e6e assetId: description: The Plerion asset identifier of the resource granting the access. type: string example: >- prn:assets:458511a1-9bc2-4fce-97a0-0e3139588e6e:aws:s3:bucket:ap-southeast-2:acme-prod-exports resourceType: description: CloudFormation resource type of the granting resource. type: string example: AWS::S3::Bucket awsAccountId: description: AWS account that owns the granting resource. type: string example: '111122223333' region: description: >- Region of the granting resource. `global` for resources that are not regional, such as IAM roles. type: string example: ap-southeast-2 assetName: description: >- Human-readable name of the granting resource. Null when the resource has no name Plerion can resolve. type: - string - 'null' example: acme-prod-exports service: description: >- AWS service the granting resource belongs to, matching the assets API. type: string example: AWS::S3 grantType: description: The specific surface within the mechanism that carries the grant. type: string example: resource_policy_statement mechanism: description: >- How the access is granted. - `resource_policy`: a resource-based policy attached to the resource - `trust_policy`: the assume-role policy of an IAM role - `ram_share`: an AWS Resource Access Manager share - `attribute_share`: a cross-account permission attribute, such as an AMI or snapshot shared with another account type: string example: resource_policy principal: description: >- The principal the access is granted to, as it appears in the policy. `*` for a grant open to everyone. type: string example: arn:aws:iam::444455556666:root principalType: description: >- What the principal is. - `public`: `*` with no narrowing condition - `conditional`: `*` narrowed by a condition, but not to a single account - `aws_org`: `*` narrowed to one AWS organization - `aws_account`, `aws_role`, `aws_user`: a specific AWS identity - `oidc`, `saml`, `external_idp`, `cognito_identity`: a federated identity - `aws_service`, `aws_support`, `canonical_user`: an AWS-owned principal type: string example: aws_account principalLabel: description: Friendly name for the principal where Plerion can resolve one. type: - string - 'null' example: Vendor - External principalDetail: description: >- Additional detail about the principal, such as the federated provider it authenticates against. type: - string - 'null' example: null principalAccountId: description: >- AWS account of the principal. Null when the principal is not tied to a single account, such as a public or federated grant. type: - string - 'null' example: '444455556666' grantScope: description: >- The trust-boundary relationship between the principal and the resource owner. - `cross-org`: the principal is in an AWS account outside your organization - `same-org`: a different account inside your organization - `same-account`: the same account as the resource - `federated`: an identity from an external identity provider - `public`: `*` with no narrowing condition - `aws-service`: an AWS service endpoint type: string example: cross-org grantOrigin: description: >- `external` when the principal is outside your organization and the grant is not blocked by a resource control policy; `internal` otherwise. type: string example: external allowedActions: description: Actions the grant allows. Null means all actions. type: - array - 'null' items: type: string example: - s3:GetObject - s3:ListBucket allowedNotActions: description: >- Actions excluded from an otherwise-broad grant, from a policy `NotAction` element. type: - array - 'null' items: type: string example: null conditions: description: >- The condition block attached to the grant, verbatim from the policy, keyed by condition operator. This is what distinguishes a grant that is genuinely open from one narrowed to your own network or organization, so it is worth reading before acting on `grantScope` alone. Null when the grant carries no conditions. type: - object - 'null' additionalProperties: true example: StringEquals: aws:PrincipalOrgID: o-abc123 blockedByRcp: description: Whether a resource control policy blocks this access today. type: boolean example: false rcpStatus: description: >- Whether resource control policies were evaluated for this grant. Null when the grant has not been evaluated. Available options: `applied`, `not-applicable`, `unknown` type: - string - 'null' example: not-applicable hasRuntimeConditions: description: >- Whether the grant carries conditions whose outcome depends on request context at runtime, such as source IP or VPC endpoint. type: boolean example: true trustStatus: description: >- Whether this grant is trusted, recalculated on every scan. Read-only. Trust has two sources and either is enough: the principal matches your tenant's trusted-principals list, or a reviewer opened a trust window on this one grant with `reviewDecision: trust_until_review` (see `trustedUntil`). Null when the grant has not been evaluated, which is the case for all `internal` grants. Available options: `trusted`, `untrusted` type: - string - 'null' example: untrusted trustedUntil: description: >- The end of the trust window a reviewer opened on this grant, from `reviewDecision: trust_until_review`. Read-only. Null when no window is open, which includes a grant trusted through the trusted-principals list instead, since that trust does not expire. A window is closed by the scan that first runs after this instant, not at the instant itself. type: - string - 'null' format: date-time example: '2027-01-31T00:00:00.000Z' trustLapseReason: description: >- Why a reviewer's trust is no longer in force. Read-only. Null while a window is open, and null when the grant never carried one. `expired` means the review date passed, `date_cleared` means the review date was removed, and `content_changed` means the grant's actions, conditions or resource scope changed after it was trusted. `content_changed` is the one needing a person: trust ended early and Plerion also cleared `reviewDecision` and `nextReviewAt`, so the grant is back to undecided. Available options: `expired`, `date_cleared`, `content_changed` type: - string - 'null' example: expired grantee: description: >- The team, person or service accountable for this access, as recorded by the most recent review that set it. type: - string - 'null' example: platform-team reviewDecision: description: >- The current decision on this grant. Null until a review records one. Available options: `keep`, `remove`, `review_later`, `trust_until_review` type: - string - 'null' example: keep reviewComment: description: The note from the most recent review that set one. type: - string - 'null' example: Vendor export feed, contract renewed 2026-07 nextReviewAt: description: >- When this grant should next be reviewed. Filter on it with `nextReviewAtEnd`. type: - string - 'null' format: date-time example: '2027-01-31T00:00:00.000Z' reviewedBy: description: >- Who last recorded a review. A user's email address, `Pleri` when the change came from the Pleri agent, or the API key name followed by `(API key)`. type: - string - 'null' example: ci-audit-key (API key) reviewedAt: description: When the most recent review was recorded. type: - string - 'null' format: date-time example: '2026-07-20T05:41:09.000Z' reviewHistory: description: >- The reviews recorded against this grant, oldest first. Null when the grant has never been reviewed. Each entry lists only the fields that review changed, so an absent field was left as it was and a field set to `null` was cleared. type: - array - 'null' items: type: object properties: reviewedBy: description: >- A user's email address, `Pleri` when the change came from the Pleri agent, or the API key name followed by `(API key)`. Null when Plerion recorded the entry itself rather than a person doing so, which is how a trust window opening or closing on its own appears. type: - string - 'null' example: my-api-key (API key) reviewedAt: type: string format: date-time example: '2026-07-20T05:41:09.000Z' decision: type: - string - 'null' enum: - keep - remove - review_later - trust_until_review - null example: keep grantee: type: - string - 'null' example: platform-team comment: type: - string - 'null' example: Vendor export feed, contract renewed 2026-07 nextReviewAt: type: - string - 'null' format: date-time example: '2027-01-31T00:00:00.000Z' trustedUntil: description: >- Present when this entry opened or closed a trust window. Null means the window closed. type: - string - 'null' format: date-time example: '2027-01-31T00:00:00.000Z' trustLapseReason: description: >- Present when this entry changed why a reviewer's trust is not in force. type: - string - 'null' enum: - expired - date_cleared - content_changed - null example: expired firstObservedAt: description: When Plerion first observed this grant. type: string format: date-time example: '2026-05-14T02:11:47.000Z' lastObservedAt: description: >- When Plerion last observed this grant. Grants no longer observed are excluded from these endpoints. type: string format: date-time example: '2026-07-28T01:03:12.000Z' InternalServerErrorResponse: type: object properties: message: type: string example: Internal server error responses: '400': description: Bad Request content: application/json: schema: properties: errors: type: array items: type: object properties: field: type: string code: type: string message: type: string '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' securitySchemes: APIKey: type: http scheme: bearer bearerFormat: apiKey description: Bearer API Key. For example, "Bearer {Tenant API Key}" ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.