API Keys¶

Endpoints for managing tenant-scoped API keys used by agents and automation. API keys provide programmatic access to the IPTO API with configurable scopes and dataset access controls.

Create API Key¶

Create a new API key for the authenticated tenant.

POST /v1/api-keys

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X POST https://api.ipto.ai/v1/api-keys \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search-agent-prod",
    "scopes": ["search:query", "usage:read"],
    "dataset_access_mode": "all_available"
  }'

import requests

response = requests.post(
    "https://api.ipto.ai/v1/api-keys",
    headers={"Authorization": "Bearer {token}"},
    json={
        "name": "search-agent-prod",
        "scopes": ["search:query", "usage:read"],
        "dataset_access_mode": "all_available",
    },
)
data = response.json()

const response = await fetch("https://api.ipto.ai/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer {token}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "search-agent-prod",
    scopes: ["search:query", "usage:read"],
    dataset_access_mode: "all_available",
  }),
});
const data = await response.json();

Request Body¶

Field	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the API key.
`scopes`	`string[]`	Yes	List of permission scopes granted to this key (e.g., `search:query`, `datasets:read`, `usage:read`).
`dataset_access_mode`	`string`	No	Controls which datasets the key can access. One of `all_available` or `allow_list`. Default: `"all_available"`.

Response¶

{
  "data": {
    "api_key_id": "key_a1b2c3d4e5f6",
    "key": "ipto_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "name": "search-agent-prod",
    "key_prefix": "sk_a1b2",
    "scopes": ["search:query", "usage:read"],
    "dataset_access_mode": "all_available",
    "created_at": "2026-04-05T10:00:00Z"
  },
  "request_id": "req_key001",
  "timestamp": "2026-04-05T10:00:00Z"
}

Response Fields¶

Field	Type	Description
`api_key_id`	`string`	Unique identifier for the API key.
`key`	`string`	The full API key secret. Shown only once at creation time.
`name`	`string`	Human-readable name.
`key_prefix`	`string`	Short prefix for identifying the key in logs and UI.
`scopes`	`string[]`	Permission scopes granted to this key.
`dataset_access_mode`	`string`	Dataset access strategy (`all_available` or `allow_list`).
`created_at`	`string`	ISO 8601 creation timestamp.

Save your key immediately

The full API key (key field) is returned only once at creation time. It cannot be retrieved later. Store it securely in your secrets manager or environment variables.

List API Keys¶

List all API keys for the authenticated tenant.

GET /v1/api-keys

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X GET "https://api.ipto.ai/v1/api-keys?limit=20" \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/api-keys",
    headers={"Authorization": "Bearer {token}"},
    params={"limit": 20},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/api-keys?limit=20",
  {
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters¶

Field	Type	Required	Description
`cursor`	`string`	No	Opaque pagination cursor from a previous response.
`limit`	`integer`	No	Maximum number of keys to return. Default: `20`.

Response¶

{
  "data": {
    "api_keys": [
      {
        "api_key_id": "key_a1b2c3d4e5f6",
        "name": "search-agent-prod",
        "key_prefix": "sk_a1b2",
        "scopes": ["search:query", "usage:read"],
        "dataset_access_mode": "all_available",
        "created_at": "2026-04-05T10:00:00Z"
      },
      {
        "api_key_id": "key_g7h8i9j0k1l2",
        "name": "ingest-worker",
        "key_prefix": "sk_g7h8",
        "scopes": ["datasets:write", "objects:write"],
        "dataset_access_mode": "allow_list",
        "created_at": "2026-04-03T08:00:00Z"
      }
    ],
    "total": 2
  },
  "request_id": "req_key002",
  "timestamp": "2026-04-05T10:01:00Z"
}

Response Fields¶

Field	Type	Description
`api_keys`	`ApiKey[]`	Array of API key objects. The `key` (secret) field is never included in list responses.
`total`	`integer`	Total number of API keys for the tenant.

Secret is not returned

The full API key secret is only returned at creation time. List and get operations return the key_prefix for identification purposes.

Get API Key¶

Retrieve details for a single API key.

GET /v1/api-keys/{id}

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X GET https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6 \
  -H "Authorization: Bearer {token}"

import requests

response = requests.get(
    "https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6",
    headers={"Authorization": "Bearer {token}"},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6",
  {
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters¶

Field	Type	Required	Description
`id`	`string`	Yes	The API key ID (path parameter).

Response¶

{
  "data": {
    "api_key_id": "key_a1b2c3d4e5f6",
    "name": "search-agent-prod",
    "key_prefix": "sk_a1b2",
    "scopes": ["search:query", "usage:read"],
    "dataset_access_mode": "all_available",
    "created_at": "2026-04-05T10:00:00Z"
  },
  "request_id": "req_key003",
  "timestamp": "2026-04-05T10:02:00Z"
}

Response Fields¶

Field	Type	Description
`api_key_id`	`string`	Unique identifier for the API key.
`name`	`string`	Human-readable name.
`key_prefix`	`string`	Short prefix for identifying the key.
`scopes`	`string[]`	Permission scopes granted to this key.
`dataset_access_mode`	`string`	Dataset access strategy.
`created_at`	`string`	ISO 8601 creation timestamp.

Revoke API Key¶

Permanently revoke an API key. Revoked keys cannot be restored.

DELETE /v1/api-keys/{id}

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X DELETE https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6 \
  -H "Authorization: Bearer {token}"

import requests

response = requests.delete(
    "https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6",
    headers={"Authorization": "Bearer {token}"},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/api-keys/key_a1b2c3d4e5f6",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters¶

Field	Type	Required	Description
`id`	`string`	Yes	The API key ID (path parameter).

Response¶

{
  "data": {},
  "request_id": "req_key004",
  "timestamp": "2026-04-05T10:03:00Z"
}

Response Fields¶

Returns an empty object on success.

Immediate effect

Revocation takes effect immediately. Any in-flight requests using the revoked key will fail with 401 Unauthorized.

Grant Dataset Access¶

Grant a specific API key access to a dataset. Only applicable when the key's dataset_access_mode is allow_list.

POST /v1/api-keys/{id}/grants

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X POST https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "dset_a1b2c3d4e5f6"
  }'

import requests

response = requests.post(
    "https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants",
    headers={"Authorization": "Bearer {token}"},
    json={
        "dataset_id": "dset_a1b2c3d4e5f6",
    },
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      dataset_id: "dset_a1b2c3d4e5f6",
    }),
  }
);
const data = await response.json();

Parameters¶

Field	Type	Required	Description
`id`	`string`	Yes	The API key ID (path parameter).

Request Body¶

Field	Type	Required	Description
`dataset_id`	`string`	Yes	The dataset ID to grant access to.

Response¶

{
  "data": {
    "grant_id": "grt_s3t4u5v6w7x8",
    "dataset_id": "dset_a1b2c3d4e5f6",
    "created_at": "2026-04-05T10:10:00Z"
  },
  "request_id": "req_key005",
  "timestamp": "2026-04-05T10:10:00Z"
}

Response Fields¶

Field	Type	Description
`grant_id`	`string`	Unique identifier for the dataset access grant.
`dataset_id`	`string`	The dataset that was granted access.
`created_at`	`string`	ISO 8601 timestamp when the grant was created.

Revoke Dataset Grant¶

Remove a dataset access grant from an API key.

DELETE /v1/api-keys/{id}/grants/{grant_id}

Authentication: Authorization: Bearer {token} or X-API-Key: ipto_{prefix}_{secret}

Scope: keys:write

Request¶

cURLPythonTypeScript

curl -X DELETE https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants/grt_s3t4u5v6w7x8 \
  -H "Authorization: Bearer {token}"

import requests

response = requests.delete(
    "https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants/grt_s3t4u5v6w7x8",
    headers={"Authorization": "Bearer {token}"},
)
data = response.json()

const response = await fetch(
  "https://api.ipto.ai/v1/api-keys/key_g7h8i9j0k1l2/grants/grt_s3t4u5v6w7x8",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer {token}" },
  }
);
const data = await response.json();

Parameters¶

Field	Type	Required	Description
`id`	`string`	Yes	The API key ID (path parameter).
`grant_id`	`string`	Yes	The grant ID to revoke (path parameter).

Response¶

{
  "data": {},
  "request_id": "req_key006",
  "timestamp": "2026-04-05T10:15:00Z"
}

Response Fields¶

Returns an empty object on success.