Quick start with Plerion API

Getting started with curl

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

Create a Tenant API key

Create a Tenant API key accessing Tenant API Keys dashboard

API Name — Add a API Key name and Create API Key

Give the key a name and choose its Role. Tenant admin, the default, can call every operation. A narrower role limits the key to the operations and integrations that role allows. See Tenant API keys.

Treat your API key like a password. Do not store it as plain text or expose it in any code base.

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={region}.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"

Overview

Plerion API uses API keys to authenticate requests. You can view and manage your API keys in the 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.

Roles and permissions

Every API key holds a role. A key with the Tenant admin role can call every operation, on every integration in the tenant. A key with the Tenant read-only role or a custom role can call only the operations its permissions allow, on the integrations the role covers. A request the role does not allow is refused with 403 Forbidden. Assign and change roles on the API keys page. See Tenant API keys. To see what a key can call, make a GET request to /v1/tenant/openapi with that key. The response is this API reference as an OpenAPI 3.1 document limited to the key. Operations the role cannot call are left out. Send Accept: application/yaml to receive YAML instead of JSON.

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

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. A 403 Forbidden with the body {"message":"Forbidden"} means the key’s role does not allow the operation. Give the key a role that holds the permission the operation needs, or use a different key. Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. Detailed description of the status code can be found in the Response Status Codes section.

Response Status Codes

The Plerion API endpoints return the following HTTP response status codes.

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.
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.

Overview

API documentation

Organization API

SCIM API

Getting started with curl

Overview

Authentication

Roles and permissions

Errors

Response Status Codes

​Getting started with curl

​Overview

​Authentication

​Roles and permissions

​Errors

​Response Status Codes

Getting started with curl

Overview

Authentication

Roles and permissions

Errors

Response Status Codes