> ## Documentation Index
> Fetch the complete documentation index at: https://docs.petrasecurity.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Petra Security API

<Note>For common API errors, see [API Troubleshooting](/api-reference/troubleshooting).</Note>

## Overview

The Petra Security API uses Bearer token authentication. Every request to the API must include a valid API key in the Authorization header.

## Getting Your API Key

API keys are managed in **Settings → API Keys**. Only **Admins** can create or delete keys. Full Members can view the key list but cannot create or delete.

To generate a new API key:

1. Go to [app.petrasecurity.com](https://app.petrasecurity.com) and sign in.
2. Navigate to **Settings** and click the **API Keys** tab.
3. Click **Create API Key**.
4. Optionally enter a description (e.g. `Production integration`) to identify the key later.
5. Click **Create API Key** in the dialog.
6. **Copy the key immediately.** The full key value is only shown once — it cannot be retrieved again after you close the dialog.

<Warning>
  Store your API key somewhere secure (e.g. a secrets manager or environment variable). Never commit it to version control or share it publicly. If a key is lost or compromised, delete it and create a new one.
</Warning>

## Managing Existing API Keys

The API Keys page lists all active keys for your organization, showing the description and creation date for each. The raw key value is never shown after the initial creation dialog.

To **delete a key**, click the trash icon next to it and confirm. Deletion is immediate — any application still using that key will start receiving `401 Unauthorized` errors. There is no undo.

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.petrasecurity.com/v1/usage
```

### Example with different languages

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    https://api.petrasecurity.com/v1/usage
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.petrasecurity.com/v1/usage', headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.petrasecurity.com/v1/usage', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Troubleshooting

### 401 Unauthorized

This error means your API key is invalid, missing, or has been deleted. Check that:

* You're including the `Bearer` prefix before your API key (e.g. `Authorization: Bearer petra_abc123...`)
* The key hasn't been deleted from **Settings → API Keys**
* You're using the key for the correct organization