canonical: https://jentic.com/apis/fusionauth.io/fusionauth

# FusionAuth API

Jentic publishes the only available OpenAPI specification for FusionAuth API, keeping it validated and agent-ready. Provides complete identity management with 314 endpoints covering user registration, application configuration, OAuth 2.0 token issuance, two-factor authentication, tenant management, and WebAuthn passkey flows. Designed for self-hosted or cloud deployment with no per-user pricing, supporting multi-tenant architectures with isolated user pools and theme customization.

## For AI agents

Register and authenticate users, configure multi-tenant applications, issue OAuth 2.0 tokens, and manage two-factor enrollment across self-hosted or cloud FusionAuth instances.

## Scope

Does not handle frontend login UI rendering, social login button styling, or client-side session cookies - use for server-side identity operations and OAuth token issuance only.

## Capabilities

- Register users to specific applications with custom role assignments and profile data
- Issue OAuth 2.0 access tokens and configure device authorization flows
- Enroll and verify two-factor authentication via TOTP, SMS, or email methods
- Configure multi-tenant environments with isolated user pools and login themes
- Link external identity providers (SAML, OIDC, social) to local user accounts
- Search users with Elasticsearch-powered queries across custom profile fields
- Trigger password reset flows and enforce tenant-specific password validation rules

## Use cases

### AI Agent User Registration

AI agents register users to FusionAuth applications through Jentic by searching for the registration operation, loading the schema (userId, applicationId, roles, data), and executing POST /api/user/registration. The agent handles the full flow from user creation to application-specific role assignment in a single session without reading FusionAuth documentation.

Example prompt: Create a user via POST /api/user with email and password, then register them to an application via POST /api/user/registration with specific roles assigned

### Multi-Tenant Identity Isolation

Configure isolated identity environments per customer or business unit using FusionAuth tenants. Each tenant has independent user pools, login themes, password policies, and email templates. The /api/tenant endpoint enables creating and configuring tenants programmatically, supporting white-label SaaS deployments where each customer gets their own branded login experience.

Example prompt: Create a new tenant via POST /api/tenant with custom password rules and email configuration, then create an application within that tenant

### Two-Factor Authentication Enrollment

Add a second factor to user accounts by generating TOTP secrets, sending SMS or email verification codes, and validating enrollment. FusionAuth supports TOTP authenticator apps, SMS-based codes, and email-based codes. The /api/two-factor/{userId} endpoints handle enrollment, and /api/two-factor/login validates codes during sign-in.

Example prompt: Generate a TOTP secret via GET /api/two-factor/secret, enroll it for a user via POST /api/user/two-factor/{userId}, then verify a code via POST /api/two-factor/login

### External Identity Provider Federation

Link external SAML 2.0, OpenID Connect, or social login providers (Google, Apple, Facebook) to FusionAuth for federated authentication. The /api/identity-provider endpoints configure provider settings, attribute mappings, and linking strategies. Users can sign in via external providers while FusionAuth maintains the canonical user record.

Example prompt: Create a SAML v2 identity provider via POST /api/identity-provider with metadata URL and attribute mappings, then initiate a login flow via POST /api/identity-provider/start

### User Search and Bulk Operations

Search across user profiles using Elasticsearch-powered queries with filters on custom data fields, registration status, and login timestamps. The /api/user/search endpoint accepts queryString or structured queries. Bulk operations like /api/user/bulk enable mass deactivation or deletion for compliance workflows.

Example prompt: Search for all users registered to a specific application who last logged in more than 90 days ago via POST /api/user/search with an Elasticsearch query, then bulk deactivate inactive accounts

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /api/user | Create a new user with profile and credentials |
| POST | /api/user/registration | Register a user to an application with roles |
| POST | /api/user/search | Search users with Elasticsearch queries |
| POST | /api/application | Create a new application configuration |
| POST | /api/tenant | Create a new tenant with isolated settings |
| POST | /oauth2/token | Issue OAuth 2.0 access and refresh tokens |
| POST | /api/user/two-factor/{userId} | Enroll two-factor authentication for a user |
| POST | /api/identity-provider | Configure an external identity provider |

## Key resources

- **Users** — Create, search, import, and manage user lifecycle including password resets and profile updates
- **Applications** — Configure applications with OAuth settings, roles, scopes, and registration options
- **Tenants** — Isolated identity environments with independent policies, themes, and email templates
- **Identity Providers** — SAML, OIDC, and social login federation with attribute mapping and linking
- **Groups** — User grouping for role-based access and application assignment
- **Two-Factor** — TOTP, SMS, and email-based second factor enrollment and verification

## Why Jentic

- **Setup:** Wiring the FusionAuth API by hand means handling both its Authorization API-key header and JWT bearer schemes, picking the right host between your sandbox and self-hosted instance, and coordinating user, application, tenant, and OAuth token calls yourself. Through Jentic you install once, import the FusionAuth API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** FusionAuth puts the user id in the URL path (/api/user/two-factor/{userId}), so a rule can pin your agent to per-user operations for that user: it acts on that record and nothing else. You choose the operations it may call, so tenant creation or identity-provider changes are not included unless you add them.
- **Credential handling:** Your FusionAuth API key or bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a user registration' or 'issue an OAuth token', and Jentic returns the matching FusionAuth operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 Authentication API** — Cloud-hosted authentication with managed infrastructure but per-user pricing
- **Okta Admin Management API** — Enterprise identity platform with extensive directory sync and policy management
- **Keycloak API** — Open-source identity server with similar self-hosting model and Red Hat backing
- **Clerk Backend API** — Frontend-focused auth with pre-built UI components for modern web frameworks

## FAQ

### Why is there no official OpenAPI spec for FusionAuth API?

FusionAuth does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call FusionAuth API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the FusionAuth API use?

The FusionAuth API uses API key authentication via the Authorization header. API keys are created in the FusionAuth admin UI and scoped to specific tenants and endpoints. Some endpoints also accept JWT bearer tokens for user-context operations. Through Jentic, API keys are stored in your Jentic One instance and agents receive properly formatted Authorization headers.

### Can I register users to specific applications with the FusionAuth API?

Yes. POST /api/user/registration accepts a userId and registration object containing applicationId, roles array, and custom data fields. Users can be registered to multiple applications within the same tenant, each with different role assignments. Through Jentic, search for 'register user to application' to load the operation schema and execute.

### What are the rate limits for the FusionAuth API?

FusionAuth is self-hosted, so rate limits depend on your deployment's hardware and configuration. The default installation has no enforced rate limits at the API level. For FusionAuth Cloud deployments, rate limits vary by plan tier. The /api/status endpoint returns server health metrics to monitor capacity.

### How do I search users by custom attributes through the FusionAuth API via Jentic?

Search Jentic for 'search fusionauth users' to find the POST /api/user/search operation. The schema accepts a search object with queryString (Elasticsearch query syntax) or structured query with filters on registrations.applicationId, data.customField, insertInstant ranges, and more. Results include full user profiles with registration data.

### Does the FusionAuth API support WebAuthn passkeys?

Yes. POST /api/webauthn/register/start initiates passkey registration by generating a challenge and credential creation options. POST /api/webauthn/register/complete finalizes registration with the authenticator response. For login, POST /api/webauthn/start generates an assertion challenge and POST /api/webauthn/assert verifies the response.

### Can I configure multiple tenants with the FusionAuth API?

Yes. POST /api/tenant creates a new tenant with its own password rules, email templates, SMTP configuration, and login theme. Each tenant has an isolated user pool. Applications are scoped to tenants. The X-FusionAuth-TenantId header routes API requests to the correct tenant when managing multi-tenant deployments.

### Can I limit what my agent is allowed to do with the FusionAuth API?

Yes. Because Jentic One is self-hosted, your own rules decide which FusionAuth operations and credentials the agent may use. Since FusionAuth carries the user id in the URL path, such as /api/user/two-factor/{userId}, you can pin the agent to per-user operations so it acts on a single record and nothing else. You choose the operations it may call, so tenant creation via POST /api/tenant or identity-provider changes via POST /api/identity-provider stay out of reach unless you explicitly add them.