Skip to content

Authentication

IPTO supports two authentication methods: session tokens for interactive use and API keys for programmatic access. Every API request must include exactly one of these credentials.

Authentication Methods

Session Tokens

Session tokens are obtained by signing up or logging in. Include the token in the Authorization header.

Authorization: Bearer {session_token}

# Interactive login
ipto login

# Non-interactive login
ipto login --email [email protected] --password pass

curl -X POST https://api.ipto.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass"}'

Session tokens are suited for:

  • Interactive sessions (dashboards, admin tools)
  • Initial setup before creating API keys
  • Short-lived scripts where a full API key is not needed

API Keys

API keys are long-lived credentials created through the API. Include the key in the X-API-Key header.

X-API-Key: ipto_{prefix}_{secret}

ipto login --api-key ipto_abc_your_key_here

curl https://api.ipto.ai/v1/datasets \
  -H "X-API-Key: ipto_abc_your_key_here"

API keys are suited for:

  • AI agents and automated pipelines
  • Server-to-server integrations
  • Any workflow that runs without human interaction

To check your current identity:

ipto whoami

curl https://api.ipto.ai/v1/me \
  -H "Authorization: Bearer $TOKEN"

When to use which

Use session tokens during development and initial setup. Use API keys for anything running in production or on a schedule.

Auth Flow

sequenceDiagram
    participant Client
    participant API as IPTO API

    alt Session token flow
        Client->>API: POST /v1/auth/signup (or /v1/auth/login)
        API-->>Client: session_token
        Client->>API: GET /v1/datasets (Authorization: Bearer token)
        API-->>Client: 200 OK
    end

    alt API key flow
        Client->>API: POST /v1/api-keys (Authorization: Bearer token)
        API-->>Client: secret (shown once)
        Client->>API: GET /v1/datasets (X-API-Key: ipto_...)
        API-->>Client: 200 OK
    end

Scopes

Every credential (session token or API key) is associated with a set of scopes that control what operations it can perform. When creating an API key, specify only the scopes your integration needs.

Scope Description
datasets:read List and read dataset metadata and objects
datasets:write Create, update, and delete datasets
objects:write Upload and manage objects within datasets
search:query Execute search queries
usage:read View usage metrics and activity history
keys:write Create, update, and revoke API keys
billing:read View billing summaries, spend, and payouts
admin:* Full administrative access (tenant owner only)

Session token scopes

Session tokens automatically inherit all scopes available to the authenticated user's role. API keys can be restricted to a subset of those scopes.

Creating an API Key

ipto keys create --name "My Agent" \
  --scopes datasets:read,search:query,objects:write

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": ["datasets:read", "search:query"]
  }'

import requests

resp = requests.post(
    "https://api.ipto.ai/v1/api-keys",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "search-agent-prod",
        "scopes": ["datasets:read", "search:query"],
    },
)
key = resp.json()
# Store key["secret"] securely -- it will not be shown again

const res = 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: ["datasets:read", "search:query"],
  }),
});
const key = await res.json();
// Store key.secret securely -- it will not be shown again

Save your API key secret

The secret field is returned only once in the creation response. IPTO does not store the raw secret and cannot retrieve it later. Copy it to a secure location (e.g., a secrets manager) immediately.

Token Lifecycle

Property Session Token API Key
Obtained via POST /v1/auth/signup or POST /v1/auth/login POST /v1/api-keys
Header Authorization: Bearer {token} X-API-Key: ipto_{prefix}_{secret}
Expiry 7 days after issuance Does not expire (revoke manually)
Revocation Expires automatically; log out to invalidate early DELETE /v1/api-keys/{api_key_id}
Scope control Inherited from user role Specified at creation time

FAQ

Can I use both auth methods at the same time?

No. Each request must include exactly one credential -- either an Authorization: Bearer header or an X-API-Key header. If both are present, the API returns a 400 Bad Request error.

How do I rotate an API key?

Create a new key with the same scopes, update your integration to use the new secret, then revoke the old key with DELETE /v1/api-keys/{old_key_id}. There is no atomic rotation endpoint, so plan for a brief overlap where both keys are active.

What scopes does my key need for search?

At minimum, a search agent needs datasets:read and search:query. Add usage:read if your agent should also access its own activity history. Add billing:read for spend tracking.

What happens when a session token expires?

After 7 days, requests using an expired session token receive a 401 Unauthorized response. Call POST /v1/auth/login with your email and password to obtain a fresh token.

Can I restrict an API key to specific datasets?

Yes. When creating or updating an API key, set dataset_access_mode to allow_list and provide an array of dataset_ids. The key will only be able to access those datasets.