Sign In Get Started

API Keys

Manage API keys programmatically for your organization.

The API Keys endpoints allow you to create, list, and revoke API keys programmatically. These endpoints require an API key with owner or admin role.

Note: API key management requires elevated permissions. Only users with owner or admin roles can manage API keys.

List API Keys

Retrieve all API keys for your organization.

GET /api/v1/api-keys/

Query Parameters

Parameter Type Required Description
organization_id string Yes UUID of the organization

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
keys = client.api_keys.list(organization_id="{{ORG_ID}}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/api-keys/",
    headers={"X-API-Key": "{{API_KEY}}"},
    params={"organization_id": "{{ORG_ID}}"}
)
data = response.json()
keys = data["api_keys"]
curl "https://api.pictograph.io/api/v1/api-keys/?organization_id={{ORG_ID}}" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/api-keys/?organization_id={{ORG_ID}}",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { api_keys } = await response.json();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/api-keys/?organization_id={{ORG_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "api_keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API",
      "key_prefix": "pk_live_abc1",
      "role": "admin",
      "rate_limit": 20000,
      "is_active": true,
      "last_used_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "expires_at": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "CI Pipeline",
      "key_prefix": "pk_live_def2",
      "role": "member",
      "rate_limit": 5000,
      "is_active": true,
      "last_used_at": "2024-01-14T08:00:00Z",
      "created_at": "2024-01-05T00:00:00Z",
      "expires_at": "2024-12-31T23:59:59Z"
    }
  ]
}

Create API Key

Create a new API key for your organization.

POST /api/v1/api-keys/

Request Body

Field Type Required Description
organization_id string Yes UUID of the organization
name string Yes Human-readable name for the key
role string No Permission level: viewer, member, admin, or owner. Default: member
expires_at string No ISO 8601 expiration date (optional)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
new_key = client.api_keys.create(
    organization_id="{{ORG_ID}}",
    name="{{KEY_NAME}}",
    role="member"
)
import requests

response = requests.post(
    "https://api.pictograph.io/api/v1/api-keys/",
    headers={
        "X-API-Key": "{{API_KEY}}",
        "Content-Type": "application/json"
    },
    json={
        "organization_id": "{{ORG_ID}}",
        "name": "{{KEY_NAME}}",
        "role": "member"
    }
)
new_key = response.json()
curl -X POST "https://api.pictograph.io/api/v1/api-keys/" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "{{ORG_ID}}",
    "name": "{{KEY_NAME}}",
    "role": "member"
  }'
const response = await fetch(
  "https://api.pictograph.io/api/v1/api-keys/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "{{API_KEY}}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      organization_id: "{{ORG_ID}}",
      name: "{{KEY_NAME}}",
      role: "member"
    })
  }
);
const newKey = await response.json();
reqBody := map[string]string{
    "organization_id": "{{ORG_ID}}",
    "name":            "{{KEY_NAME}}",
    "role":            "member",
}
jsonBody, _ := json.Marshal(reqBody)

req, _ := http.NewRequest("POST",
    "https://api.pictograph.io/api/v1/api-keys/",
    bytes.NewBuffer(jsonBody))
req.Header.Set("X-API-Key", "{{API_KEY}}")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand

Important: The full API key is only returned once during creation. Store it securely - you won't be able to retrieve it again.

JSON 
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "key": "pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "key_prefix": "pk_live_a1b2",
  "name": "New API Key",
  "role": "member",
  "rate_limit": 5000,
  "is_active": true,
  "created_at": "2024-01-16T00:00:00Z",
  "expires_at": null
}

Get API Key

Retrieve details for a specific API key.

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

Path Parameters

Parameter Type Description
key_id string UUID of the API key

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
key_details = client.api_keys.get("{{KEY_ID}}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
key_details = response.json()
curl "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const keyDetails = await response.json();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API",
  "key_prefix": "pk_live_abc1",
  "role": "admin",
  "rate_limit": 20000,
  "is_active": true,
  "last_used_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "expires_at": null
}

Update API Key

Update an existing API key's name, rate limit, or active status.

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

Request Body

Field Type Description
name string New name for the key
rate_limit integer New rate limit (requests per hour)
is_active boolean Enable or disable the key

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.api_keys.update(key_id="{{KEY_ID}}", name="Updated Name")
import requests

response = requests.patch(
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
    headers={
        "X-API-Key": "{{API_KEY}}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Name",
        "is_active": True
    }
)
curl -X PATCH "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "is_active": true
  }'
await fetch(
  "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "{{API_KEY}}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Updated Name",
      is_active: true
    })
  }
);
reqBody := map[string]interface{}{
    "name":      "Updated Name",
    "is_active": true,
}
jsonBody, _ := json.Marshal(reqBody)

req, _ := http.NewRequest("PATCH",
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
    bytes.NewBuffer(jsonBody))
req.Header.Set("X-API-Key", "{{API_KEY}}")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)

Delete API Key

Permanently revoke an API key. This action cannot be undone.

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

Path Parameters

Parameter Type Description
key_id string UUID of the API key to delete

Response

Returns 204 No Content on success.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.api_keys.delete("{{KEY_ID}}")
import requests

response = requests.delete(
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
curl -X DELETE "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}" \
  -H "X-API-Key: {{API_KEY}}"
await fetch(
  "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}",
  {
    method: "DELETE",
    headers: { "X-API-Key": "{{API_KEY}}" }
  }
);
req, _ := http.NewRequest("DELETE",
    "https://api.pictograph.io/api/v1/api-keys/{{KEY_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)

Error Responses

Status Error Description
401 invalid_api_key Missing or invalid API key
403 forbidden API key does not have owner/admin role
404 not_found API key not found
409 conflict API key with this name already exists
Copied to clipboard