API Keys Management

Manage your API keys with an API key. These endpoints act on the keys you created, and the calling key needs full access, keys:read to list or keys:write to change, or the legacy manage scope.

Endpoints

List API Keys

Retrieve all API keys you created.

GET /api/v1/api-keys

Headers:

X-API-Key: your_api_key

Response (200 OK)

[
  {
    "id": "45ab9041-1825-4238-a829-5b8431c6d401",
    "name": "Production API",
    "prefix": "pg_live_rG1cJhTf",
    "key": null,
    "project_id": "910b6423-8a12-4461-a6bf-9148d9b6b8e3",
    "project_name": "My Project",
    "permissions": [],
    "is_active": true,
    "last_used_at": "2026-10-31T12:49:25.556820+00:00",
    "expires_at": null,
    "created_at": "2026-10-31T12:43:02.531286+00:00",
    "rate_limit_per_minute": null,
    "grants": [
      { "group": "scan", "level": "write" },
      { "group": "proxy", "level": "write" }
    ],
    "monthly_request_cap": 100000,
    "requests_this_month": 2311
  }
]

grants is what the key reaches, by scope, whichever way its permissions name it; a single-action scope is always write. An export key and an enrolled device’s credential list none. requests_this_month counts against monthly_request_cap, and is 0 for a key with no cap.

key is always null here. The full key is returned once, by Create, and cannot be retrieved afterwards: PromptGuard stores only a one-way digest of it. If you lose a key, create a new one and delete the old one.

Create API Key

POST /api/v1/api-keys

Request Body

{
  "name": "Production API",
  "project_id": "910b6423-8a12-4461-a6bf-9148d9b6b8e3"
}

Parameter	Type	Required	Description
`name`	`string`	Yes	1 — 50 characters: letters, numbers, spaces, hyphens and underscores
`project_id`	`string`	No	The project the key acts for (its UUID). It must be one of yours, or the call returns 404. If omitted, the calling key’s project; if that is not one of yours, required (422)
`permissions`	`string[]`	No	Scopes such as `scan:write` and `policies:read`, or the legacy `proxy`, `manage` and `read`; see Scopes. Omitted or empty is full access until 2027-02-06, and `scan` + `proxy` from then; see No permissions
`expires_at`	`datetime`	No	When the key stops working. No expiry if omitted. If the calling key expires, required and no later than the calling key’s
`rate_limit_per_minute`	`integer`	No	The new key’s own requests-per-minute limit, a whole number of at least 1, beside your plan’s; see Per-key limits. No limit of its own if omitted. If the calling key has one, required and no higher
`monthly_request_cap`	`integer`	No	The new key’s own monthly request cap, a whole number of at least 1. No cap of its own if omitted. If the calling key has one, required and no higher

Response (200 OK)

{
  "key": "pg_live_T86tIKrs_...",
  "id": "222a24bd-2249-423b-b36c-76503a9a3004",
  "name": "Production API",
  "prefix": "pg_live_T86tIKrs"
}

The key field is only returned once, in this response. Store it securely — you won’t be able to see it again.

No permissions

A key created here with permissions omitted or empty has full access today. That is deprecated: from 2027-02-06, it gets scan + proxy, the scopes application traffic needs, as a key created in the dashboard does. Until then, each such response carries a Deprecation: true header, a Sunset header with that date and a Link header to this section. Keys created before the date keep the access they have. To keep creating full-access keys after the date, send "permissions": ["*"]. To get the new behaviour now, send "permissions": ["scan:write", "proxy:write"].

Scopes

A key with scopes reaches only the endpoints its scopes cover, and is refused any other with 403 scope_denied. A scope is a resource group and a level, <group>:<level>, and the same one covers an endpoint under /api/v1/proxy where it is also served there. scan, proxy and red_team have one action each, so :read and :write reach the same endpoints. For the others, read reaches the endpoints that read and write those that change too:

Scope	Endpoints
`scan`	`/guard`, `/security/`, `/mcp/`, `/agent/*`
`proxy`	`/chat/completions`, `/messages`, `/responses`, `/models`
`red_team`	`/security-testing/*`
`usage`	`/usage/*`
`policies`	`/overlays`, `/projects/{project_id}/guardrails`
`shadow`	`/fleet/*`, `/exceptions`, `/policies`, `/tool-requests`
`projects`	`/projects`
`keys`	`/api-keys`

A key created in the dashboard gets scan:write and proxy:write unless you choose otherwise. Other groups exist for other credentials, and a key cannot hold them: events and audit on /api/v1 read the whole organization, which only an export key does, and integrations, team and billing_org have no /api/v1 endpoint. Creating a key with one is refused with 422, as is a misspelt group or level. A key with scopes can create only keys whose scopes it already covers: a keys:write key can create a keys:read key, but not a policies:read key or one with no scopes. Organization-wide export keys are created in the dashboard, not here.

Legacy scopes

Keys created before resource groups carry these scopes, and keep exactly the access they had. Each covers several groups:

Scope	Endpoints
`proxy`	`/chat/completions`, `/messages`, `/responses`, `/models`, `/guard`, `/security/`, `/security-testing/`, `/mcp/`, `/agent/`
`manage`	`/api-keys`, `/projects`, `/overlays`, `/policies`, `/fleet/*`, `/exceptions`, `/tool-requests`
`read`	`/usage/*`

A key with no scopes, or with both read and write, has full access. write alone covers proxy and manage. A key may carry legacy scopes and groups together; it reaches what either covers.

Monthly request cap

A key can carry a cap on the requests it makes each calendar month (UTC), beside your plan’s quota. Past it, the key is refused with 429 api_key_request_cap_exceeded until the first of next month, and resets_at says when; your other keys are still served. Set it when you create the key, here or in the dashboard. Rotating a key keeps its cap, and the new key counts from zero. Key limits by plan. The cap counts the keys in the organization that owns the key’s project:

Plan	Max API keys per organization
Free	1
Developer	Unlimited

At the cap, create returns 403 with a message such as API key limit reached. Free plan allows 1 API key(s). Upgrade to Developer for unlimited API keys.

Delete API Key

Permanently delete an API key. This immediately revokes access.

DELETE /api/v1/api-keys/{key_id}

Parameter	Type	In	Description
`key_id`	`string`	Path	ID of the key to delete

Response (204 No Content), with an empty body.

Toggle API Key Status

Enable or disable an API key without deleting it.

PUT /api/v1/api-keys/{key_id}/toggle

Parameter	Type	In	Description
`key_id`	`string`	Path	ID of the key to toggle

Response (200 OK)

{
  "success": true,
  "is_active": false
}

Use toggle instead of delete when you want to temporarily disable a key (e.g., during incident response) without losing the key configuration. A disabled key is refused with 401 disabled_api_key.

Code Examples

Python
Node.js
cURL

import requests
import os

api_key = os.environ.get("PROMPTGUARD_API_KEY")
base_url = "https://api.promptguard.co/api/v1/api-keys"

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

# List all API keys
response = requests.get(base_url, headers=headers)
keys = response.json()
for key in keys:
    print(f"{key['name']}: {key['prefix']}... (active: {key['is_active']})")

# Create a new API key
response = requests.post(base_url, headers=headers, json={
    "name": "Backend Service",
    "project_id": "<your-project-id>"
})
new_key = response.json()
print(f"New key: {new_key['key']}")  # Save this!

# Toggle a key off
requests.put(f"{base_url}/{new_key['id']}/toggle", headers=headers)

# Delete a key
requests.delete(f"{base_url}/{new_key['id']}", headers=headers)

const apiKey = process.env.PROMPTGUARD_API_KEY;
const baseUrl = 'https://api.promptguard.co/api/v1/api-keys';

const headers = {
  'X-API-Key': apiKey,
  'Content-Type': 'application/json'
};

// List all API keys
const keys = await fetch(baseUrl, { headers }).then(r => r.json());
keys.forEach(key => {
  console.log(`${key.name}: ${key.prefix}... (active: ${key.is_active})`);
});

// Create a new API key
const newKey = await fetch(baseUrl, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Backend Service',
    project_id: '<your-project-id>'
  })
}).then(r => r.json());
console.log(`New key: ${newKey.key}`); // Save this!

// Toggle a key off
await fetch(`${baseUrl}/${newKey.id}/toggle`, {
  method: 'PUT',
  headers
});

// Delete a key
await fetch(`${baseUrl}/${newKey.id}`, {
  method: 'DELETE',
  headers
});

# List all API keys
curl https://api.promptguard.co/api/v1/api-keys \
  -H "X-API-Key: $PROMPTGUARD_API_KEY"

# Create a new API key
curl -X POST https://api.promptguard.co/api/v1/api-keys \
  -H "X-API-Key: $PROMPTGUARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend Service", "project_id": "<your-project-id>"}'

# Toggle API key status
curl -X PUT https://api.promptguard.co/api/v1/api-keys/{key_id}/toggle \
  -H "X-API-Key: $PROMPTGUARD_API_KEY"

# Delete API key
curl -X DELETE https://api.promptguard.co/api/v1/api-keys/{key_id} \
  -H "X-API-Key: $PROMPTGUARD_API_KEY"

Error Responses

Status	Body	Description
401	`{"error": {"code": "invalid_api_key", ...}}`	Invalid, disabled or expired calling key (`invalid_api_key`, `disabled_api_key`, `expired_api_key`), or none (`missing_api_key`)
403	`{"error": {"code": "HTTP_ERROR", "message": "API key limit reached. ..."}}`	Your plan’s key cap is reached
403	`{"error": {"code": "scope_denied", ...}}`	The calling key has scopes, and `manage` is not among them
403	`{"error": {"code": "scope_denied", ...}}`	On create: the calling key has scopes, and `permissions` asks for one it does not cover, or for full access
403	`{"error": {"code": "scope_denied", ...}}`	On create: the calling key expires and `expires_at` is later or missing, or it has a per-minute limit and `rate_limit_per_minute` is higher or missing
404	`{"error": {"code": "HTTP_ERROR", "message": "API key not found"}}`	No key with that ID among yours. `"Project not found"` when `project_id` is not one of your projects
422	`{"detail": [...]}`	The body failed validation, for example a `name` missing or with other characters, or `project_id` missing when the calling key’s project is not one of yours. Each problem’s `loc` names the field

Best Practices

Name keys descriptively — Use names like “Production Backend” or “Staging Cron Job” so you can identify them later
One key per service — Don’t share keys between applications
Rotate every 90 days — Create new key → update apps → delete old key
Use toggle for incidents — Disable a compromised key immediately without losing the configuration
Monitor last_used_at — Delete keys that haven’t been used in a while

Overview

Endpoints

SDK Reference

API Reference

api-keys

usage

projects

SIEM export

guardrails

fleet-device

agent

security

mcp

security-testing

guard

enroll

shadow-exceptions

policies

overlays

tool-requests

GitHub Webhooks

API Keys Management

API Keys Management

Endpoints

List API Keys

Create API Key

No permissions

Scopes

Legacy scopes

Monthly request cap

Delete API Key

Toggle API Key Status

Code Examples

Error Responses

Best Practices

​API Keys Management

​Endpoints

​List API Keys

​Create API Key

​No permissions

​Scopes

​Legacy scopes

​Monthly request cap

​Delete API Key

​Toggle API Key Status

​Code Examples

​Error Responses

​Best Practices

API Keys Management

Endpoints

List API Keys

Create API Key

No permissions

Scopes

Legacy scopes

Monthly request cap

Delete API Key

Toggle API Key Status

Code Examples

Error Responses

Best Practices