API Keys¶

API keys are machine-to-machine credentials that allow your applications, agents, and automation workflows to authenticate with the IPTO API.

What are API keys?¶

Each API key is scoped to a single tenant and carries a set of permissions (scopes) that determine which API operations it can perform. API keys are designed for programmatic access -- use them in your backend services, search agents, and data pipelines.

API keys are independent of user accounts. They can be created, rotated, and revoked without affecting team member access.

Key format¶

IPTO API keys follow a structured format that makes them easy to identify in logs and configuration files:

ipto_{prefix}_{secret}

ipto_ -- A fixed namespace prefix identifying the key as an IPTO credential.
{prefix} -- A short, non-secret identifier used for key lookup and audit trails. This portion is safe to log.
{secret} -- The secret portion of the key. This is sensitive and must never be logged or exposed.

Secret visibility

The full API key secret is returned only once at creation time. Store it securely immediately. If you lose the secret, you must revoke the key and create a new one.

Scopes¶

Every API key carries one or more scopes that control which API operations the key can perform.

Scope	Description
`datasets:read`	Read dataset metadata, list datasets, and browse the catalog.
`datasets:write`	Create, update, and manage datasets.
`objects:write`	Upload objects, initiate uploads, and confirm uploads.
`search:query`	Execute search queries across accessible datasets.
`usage:read`	Read usage metrics, search activity, and access history.
`keys:write`	Create, update, and revoke API keys for the tenant.
`billing:read`	Read billing summaries, invoices, and payout statements.
`admin:*`	Full administrative access across all tenant operations.

Assign the minimum set of scopes each key needs. A search agent typically only requires search:query, while a data ingestion pipeline needs datasets:write and objects:write.

Dataset access modes¶

In addition to scopes, each API key has a dataset access mode that controls which datasets the key can interact with.

Mode	Description
`all_available`	The key can access all datasets currently available to the tenant. This is the default for new keys.
`allow_list`	The key can only access datasets that have been explicitly granted to it.

Info

Dataset access restrictions on a key can only narrow the tenant's access. A key can never access a dataset that the tenant itself does not have access to.

Dataset grants¶

When a key uses the allow_list access mode, you manage access by adding or removing dataset grants:

Adding a grant gives the key access to a specific dataset.
Removing a grant revokes the key's access to that dataset.

This allows you to create purpose-specific keys. For example, a search agent for legal documents might only have grants for legal-related datasets, while a financial analysis agent has grants for financial datasets.

Access control flow¶

When a request arrives, IPTO evaluates the API key through the following access control sequence:

flowchart TD
    A[Incoming request] --> B{Valid API key?}
    B -- No --> C[401 Unauthorized]
    B -- Yes --> D{Required scope present?}
    D -- No --> E[403 Forbidden]
    D -- Yes --> F{Dataset access mode?}
    F -- all_available --> G[Execute request]
    F -- allow_list --> H{Dataset in grant list?}
    H -- Yes --> G
    H -- No --> I[403 Forbidden]

Security best practices

Use separate keys for separate concerns. Create distinct keys for search agents, data pipelines, and administrative scripts.
Apply least-privilege scopes. Only grant the scopes each key actually needs.
Use allow_list for sensitive workflows. Restrict keys to the specific datasets they should access rather than granting blanket access.
Rotate keys regularly. Periodically revoke and replace keys, especially after team changes.
Never embed keys in client-side code. API keys are server-side credentials. Do not expose them in browser applications, mobile apps, or public repositories.
Monitor key usage. Use the usage and activity APIs to audit which keys are accessing which datasets.

FAQ¶

How many API keys can I create?

The number of API keys you can create depends on your plan tier. All plans support multiple keys. Check your plan details for the exact limit.

Can I change the scopes on an existing key?

You can update the name, dataset access mode, and dataset grant list on an existing key. To change scopes, revoke the current key and create a new one with the desired scopes.

What happens if I revoke a key that is in active use?

Revoking a key takes effect immediately. Any in-flight requests authenticated with that key will complete, but subsequent requests will receive a 401 Unauthorized response. Make sure to update your applications before revoking a key.

Does all_available mean the key can access every dataset on the platform?

No. all_available means the key can access all datasets available to your tenant. If your tenant has not been granted access to a restricted dataset, the key cannot access it either. The key inherits the tenant's access set, not the entire marketplace.

Can I see which API key made a specific request?

Yes. Every API request is logged with the api_key_id that authenticated it. You can view activity by key through the search activity and access history endpoints, or in the dashboard.