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.
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.
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.
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.
| Status Code | Definition | Description |
|---|---|---|
| 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. |
| 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. |
588158338731au.api.plerion.comcurl command.
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')
# Generate the temporary auth token
export TEMP_AUTH_TOKEN=$(curl -s -X POST "https://$PLERION_API_URL/v1/tenant/integrations/token" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.token')
# 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')
# 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=AuthToken,ParameterValue=$TEMP_AUTH_TOKEN \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS" \
ParameterKey=PlerionURL,ParameterValue=$PLERION_API_URL
# Wait for the stack to complete
aws cloudformation wait stack-create-complete --stack-name $PLERION_STACK_NAME
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')
# Generate the temporary auth token
export TEMP_AUTH_TOKEN=$(curl -s -X POST "https://$PLERION_API_URL/v1/tenant/integrations/token" -H "Authorization: Bearer $PLERION_API_KEY" | jq -r '.data.token')
# 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')
# 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=AuthToken,ParameterValue=$TEMP_AUTH_TOKEN \
ParameterKey=Capabilities,ParameterValue=ALL \
ParameterKey=KMSKeyAccessMode,ParameterValue="ALL_KEYS" \
ParameterKey=PlerionURL,ParameterValue=$PLERION_API_URL
# 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.
paths:
/v1/tenant/aws/access-grants/{id}:
get:
tags:
- AWS access grants
summary: Get
description: Fetch a single access grant by its ID.
operationId: getTenantAccessGrant
parameters:
- $ref: '#/components/parameters/paramAuthHeader'
- in: path
name: id
required: true
description: >-
The ID of the access grant. A value that is not a UUID returns a
`400`.
schema:
type: string
example: 0f9a1c3e-5b7d-4c21-9e8f-2a6b4d10c7f3
responses:
'200':
description: The access grant
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccessGrant'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'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 the principal is trusted, based on your tenant's
trusted-principals list and recalculated on every scan. Read-only.
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
grantOwner:
description: >-
Who owns 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`
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)`.
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
- null
example: keep
owner:
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'
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
'404':
description: Not Found
content:
application/json:
schema:
properties:
errors:
type: array
items:
type: object
properties:
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}"
````