---
title: "Integration API"
icon: "cube"
description: "Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions"
---

import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

<PangolinCloudTocCta />


<Warning>
Pangolin is in heavy development. The REST API routes and behavior may include breaking changes between updates. We will do our best to document large changes.
</Warning>

The API is REST-based and supports many operations available through the web interface. Authentication uses Bearer tokens, and you can create multiple API keys with specific permissions for different use cases.

For self-hosted editions, the integration API must be enabled. Check out [the documentation](/self-host/advanced/integration-api) for how to enable the integration API.

## Authentication

All API requests require authentication using a Bearer token in the Authorization header:

<CodeGroup>
```bash cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/
```

```javascript JavaScript
const response = await fetch('https://api.example.com/v1/endpoint', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
```

```python Python
import requests

headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get('https://api.example.com/v1/endpoint', headers=headers)
```
</CodeGroup>

## API Key Types

Pangolin supports two types of API keys with different permission levels:

### Organization API Keys

Organization API keys are created by organization admins and have limited scope to perform actions only in that organization.

### Root API Keys

Root API keys have some extra permissions and can execute operations across orgs. They are only available in the fully self-hosted editions of Pangolin:

<Warning>
Root API keys have elevated permissions and should be used carefully. Only create them when you need server-wide access.
</Warning>

## Creating API Keys

<Steps>
<Step title="Access the admin panel">
  Navigate to your admin panel:
  - **Organization keys**: Organization → API Keys
  - **Root keys**: Server Admin → API Keys (self-hosted only)
</Step>

<Step title="Generate a new key">
  Click "Create API Key" and provide a descriptive name for the key.
</Step>

<Step title="Configure permissions">
  Select the specific permissions your API key needs from the permissions selector.
  
  <Frame caption="API key permissions selector showing available operations">
  <img src="/images/permissions.png" alt="API Key Permissions"/>
  </Frame>
</Step>

<Step title="Copy and secure your key">
  Copy the generated API key immediately. It won't be shown again.
  
  <Warning>
  Store API keys securely and never commit them to version control. Use environment variables or secure secret management.
  </Warning>
</Step>
</Steps>

## API Documentation

For a minimal walkthrough of common flows (sites, resources, targets, assigning roles and users), see [Common API Routes](/manage/common-api-routes).

View the full Swagger docs here: [https://api.pangolin.net/v1/docs](https://api.pangolin.net/v1/docs).

Interactive API documentation is available through Swagger UI:

<Frame caption="Swagger UI showing API endpoints and interactive testing">
<img src="/images/swagger.png" alt="Swagger Docs"/>
</Frame>

For self-hosted Pangolin, access the documentation at `https://api.your-domain.com/v1/docs`.
