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

# Authentication

> Authenticate with the PG:AI API using API keys

All API requests (except `/health`) require authentication via an API key passed in the `x-api-key` request header.

## Getting Your API Key

<Steps>
  <Step title="Navigate to settings">
    Go to **Settings > API Keys** in your PG:AI workspace.
  </Step>

  <Step title="Generate a key">
    Click **Generate API Key**, give it a descriptive name, and select the permission scopes it should have.
  </Step>

  <Step title="Copy and store securely">
    Copy the key immediately — it won't be shown again. Store it in environment variables or a secrets manager.
  </Step>
</Steps>

## Using Your API Key

Include the API key in the `x-api-key` header on every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getpg.ai/public-api/v1/territories" \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: application/json"
  ```

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

  headers = {
      "x-api-key": "your_api_key",
      "Content-Type": "application/json"
  }

  response = requests.get(
      "https://api.getpg.ai/public-api/v1/territories",
      headers=headers
  )

  data = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.getpg.ai/public-api/v1/territories", {
    method: "GET",
    headers: {
      "x-api-key": "your_api_key",
      "Content-Type": "application/json"
    }
  });

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

<Warning>
  Never expose your API key in client-side code, public repositories, or browser requests. Always keep it server-side.
</Warning>

## Base URL

All API endpoints use the following base URL:

```
https://api.getpg.ai/public-api/v1
```

## Permissions & Scopes

API keys are scoped with granular permissions. Each endpoint requires a specific permission — requests made with a key that lacks the required scope will receive a `403 Forbidden` response.

| Scope               | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `accounts:read`     | Search and list accounts                                      |
| `companies:read`    | Read company data (relevance, graph, search, jobs, canvas)    |
| `contacts:read`     | Read contact data                                             |
| `contacts:write`    | Create or enrich contacts                                     |
| `insights:read`     | Read company intelligence, profiles, alerts, and technologies |
| `insights:write`    | Create or modify company enrichment data                      |
| `integrations:read` | Read integration status                                       |
| `jobs:read`         | Read job postings                                             |
| `monitoring:read`   | Read monitoring events                                        |
| `monitoring:write`  | Manage monitoring events                                      |
| `org_settings:read` | Read organization settings and credits                        |
| `sequences:read`    | Read sequences and templates                                  |
| `sequences:write`   | Create or modify sequences                                    |
| `tasks:read`        | Read tasks                                                    |
| `tasks:write`       | Create or modify tasks                                        |
| `territories:read`  | Read territories and their companies                          |
| `workflows:read`    | Read workflows                                                |
| `workflows:execute` | Trigger workflow executions                                   |
| `*`                 | Full access (all permissions)                                 |

Wildcard scopes are also supported. For example, `insights:*` grants both `insights:read` and `insights:write`.

## Rate Limits

API requests are rate-limited based on your plan. If you exceed the limit, the API returns a `429 Too Many Requests` response.

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window       |
| `X-RateLimit-Remaining` | Requests remaining in current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets |

<Tip>
  If you're hitting rate limits, consider batching requests or adding short delays between calls.
</Tip>

## Error Responses

All error responses follow a consistent structured format. Every error includes a `type`, a machine-readable `code`, and a human-readable `message`. Some errors include a `details` object with additional context.

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_uuid",
    "message": "Not a valid UUID.",
    "details": {}
  }
}
```

All responses (including errors) include an `X-Request-Id` header you can use when contacting support to identify the specific request.

| Status Code | Description                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| `400`       | Bad Request — invalid parameters or missing required fields                        |
| `401`       | Unauthorized — missing or invalid API key                                          |
| `402`       | Insufficient Credits — your organization has run out of credits for this operation |
| `403`       | Forbidden — API key lacks the required permission scope                            |
| `404`       | Not Found — the requested resource does not exist                                  |
| `429`       | Rate Limited — too many requests, slow down and retry                              |
| `500`       | Internal Server Error — something went wrong on our end                            |
| `503`       | Service Unavailable — a downstream service is temporarily unreachable              |