---
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 Pangolin Community Edition, 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`.
