Core API Reference

AuthPI Core API

Version 1.0.0 — base URL https://api.authpi.com. Fetch the raw OpenAPI spec (JSON).

Endpoints

Me — 1 operations. Caller identity.
Accounts — 12 operations. Account management endpoints.
Account Domains — 6 operations. Custom domain management for an account: add, verify, and remove domains used for white-labeled portals and issuers.
Issuers — 10 operations. Issuer management endpoints.
Clients — 6 operations. OAuth 2.0 client management endpoints.
Agents — 8 operations. Agent identity management endpoints.
Users — 17 operations. User management endpoints.
Organizations — 24 operations. Organization management endpoints.
Sessions — 5 operations. User session management endpoints.
Events — 3 operations. Audit event endpoints.
Webhooks — 8 operations. Webhook management endpoints.
API Keys — 11 operations. Organization API key management.
Personal Tokens — 5 operations. User personal access token management.
Token Introspection — 1 operations. Validate API keys and personal tokens.
Notes — 7 operations. Admin/team notes management.
Approvals — 3 operations. Signup approval queue management.

About this API

The AuthPI Core API provides programmatic access to manage your identity infrastructure. Use this API to create and configure issuers, manage users, handle organizations, and monitor your authentication system.

Overview

This API enables you to:

Manage Accounts - Configure billing and administrative settings
Configure Issuers - Set up identity providers with authentication methods, policies, and branding
Register Clients - Create OAuth 2.0/OIDC applications that authenticate users
Manage Users - Create, update, and delete user identities
Handle Organizations - Group users for multi-tenant applications
Monitor Sessions - View and control active user sessions
Track Events - Access audit logs for compliance and debugging
Configure Webhooks - Set up real-time event notifications

Resource Hierarchy

AuthPI resources follow a hierarchical structure:

Account
├── Issuers (identity providers)
│   ├── Users (identities)
│   │   ├── Sessions
│   │   ├── Verifiers (passwords, passkeys)
│   │   └── Personal Tokens
│   ├── Clients (OAuth applications)
│   ├── Agents (non-human identities)
│   └── Organizations (user groups)
│       ├── Members
│       └── API Keys
├── Webhooks
└── Events

Authentication

The API supports two authentication modes:

Org API keys (HTTP Basic) — the standard mode for backend integrations. Use the key id as the username and the key secret as the password:

curl -u "key_id:key_secret" https://api.authpi.com/v1/accounts/{account_id}/issuers

Bearer JWT — for user-context access (e.g. the AuthPI console, or tokens obtained via OAuth flows):

Authorization: Bearer {access_token}

Idempotency

The API supports the Idempotency-Key header on POST requests to safely retry operations without creating duplicate resources. This is especially useful for AI agents, webhook handlers, and any client operating over unreliable networks.

Include a unique key (1–256 characters) in the header:

Idempotency-Key: your-unique-key

Behavior:

The first request with a given key executes normally. Subsequent requests with the same key and body replay the original response with an Idempotent-Replayed: true header.
Keys are scoped per account and expire after 24 hours.
Using the same key with a different request body returns 422 Unprocessable Content.
Concurrent requests with the same key return 409 Conflict with a Retry-After header.
Only successful (2xx) responses are cached. Failed requests release the key for retry.
The header is silently ignored on non-POST methods (GET, PATCH, DELETE are naturally idempotent).
Endpoints that return one-time secrets (e.g., API key creation, client secret rotation) are excluded from caching to preserve the “returned once” guarantee.

See the Idempotency guide for detailed usage patterns and examples.

Rate Limiting

API requests are rate-limited to ensure fair usage. Rate limits vary by endpoint and plan. When rate-limited, you'll receive a 429 Too Many Requests response with a Retry-After header.

Pagination

List endpoints support cursor-based pagination:

limit - Number of items to return (default: 50, max: 100)
cursor - Cursor from previous response for next page

Optimistic Concurrency (ETags)

The API uses ETags for optimistic concurrency control on single-resource responses. This prevents silent data loss when multiple clients update the same resource concurrently.

Reading ETags: Every GET, PATCH, and POST (create) response for a single resource includes an ETag header:

ETag: "1709139600000"

The value is a quoted timestamp derived from the resource's last modification time. List responses ({ data: [], has_more }) do not include ETags.

Conditional updates: To guard against overwriting concurrent changes, include the If-Match header on PATCH or DELETE requests:

If-Match: "1709139600000"

If the resource has not changed since the ETag was issued, the request proceeds normally.
If the resource has changed, the API returns 412 Precondition Failed with the current ETag in the error details.
If If-Match is omitted, the request proceeds unconditionally (last-write-wins, backward compatible).
The wildcard If-Match: * always matches.

See the Conditional Requests guide for detailed usage patterns, retry strategies, and examples.

Support

For questions or support, contact us at contact@authpi.com.