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

# Quick start with Plerion API

> 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

<Steps>
  <Step title="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](https://curl.se/download.html)
  </Step>

  <Step title="Create a Tenant API key">
    Create a Tenant API key accessing [Tenant API Keys dashboard](https://app.plerion.com/settings/api-keys)

    <Frame caption="Go to Settings > API Keys">
      <img src="https://mintcdn.com/pleriondocs/rGvQ5xgTVRw_KLys/images/product/api-keys/image01.png?fit=max&auto=format&n=rGvQ5xgTVRw_KLys&q=85&s=a37bc1edd73068052a6d75b6f60f8b68" alt="API Key" width="2001" height="884" data-path="images/product/api-keys/image01.png" />
    </Frame>

    <br />

    <Frame caption="Add a API Key name and Create API Key">
      <img src="https://mintcdn.com/pleriondocs/rGvQ5xgTVRw_KLys/images/product/api-keys/image02.png?fit=max&auto=format&n=rGvQ5xgTVRw_KLys&q=85&s=d925964aa3c02909d4bbf3d413a72015" alt="API Name" width="3158" height="910" data-path="images/product/api-keys/image02.png" />
    </Frame>

    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](/guides/administration/api-keys).

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

  <Step title="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"
    ```
  </Step>
</Steps>

## 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](https://app.plerion.com/settings/api-keys). See [Tenant API keys](/guides/administration/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.

```bash theme={"system"}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.