Not all email related functionality is available when using user.data.email, but common workflows like forgot password are.

Entity types are like classes in an object-oriented programming language, which define the permissions that an entity can have.

Entities are similar to objects, in that they are an instantiation of an entity type. No behavior though, and no inheritance.

Entities are connected to users and other entities via grants. You can think of this setting up a directed permission graph that can be traced.

0 to N permissions are attached to each grant.

There are three major uses for entities:

A few notes about entities:

https://fusionauth.io/docs/get-started/core-concepts/tenants#advanced has more details.

⚠ Preview Warning: The FusionAuth MCP server is a preview release and may break, change, or be discontinued. It is intended for development and test instances. Never give an MCP client unrestricted access to a production instance.

This lets you configure FusionAuth and record steps to apply to other instances.

Restart Claude Desktop after saving.

"Which tools do you have access to?"

You should see a list of all FusionAuth API tools (300+).

"Set up a custom registration form for the Pied Piper application. Require email address and password, but allow first name and favorite color to be optional. Put them all on one page."

Or:

"Add a user with an email address of test@example.com and a password of password."

The agent will make the appropriate API calls on your behalf.

"Please export the configuration for the Pied Piper application to a kickstart file."

"Export the current tenant configuration as a Terraform file."

This gives you a reproducible artifact you can commit to source control or use in CI/CD pipelines.

You can reduce tool scope. If you only need to work with specific operations (e.g., no deletes), you can reduce the tool list to improve performance and limit risk:

This omits the delete APIs and reduces the tool list by ~20%.

The security model of this approach consists of three layers: the instance you connect to, the tool categories you expose, and the permissions on the API key itself. Combining a read-only API key with USE_TOOLS="retrieve,search" gives you defense in depth for production queries.

Setting USE_TOOLS="retrieve,search" reduces the tool list by 66% and ensures the agent cannot create, update, patch, or delete anything. This is a second layer of defense.

"Which tools do you have access to?"

Confirm that only retrieve and search tools are listed — no create, update, delete, or patch tools should appear.

Query production data. You can now safely ask questions like:

The agent will use the read-only API tools to answer your questions without modifying anything.

I also found this on the users accounts being locked.

If this information does not get you where you need, please let me know.

However, the easiest way to make sure an application cannot be logged into is to deactivate the application.

In the response, look at the total field.

This will let you get exact numbers while reducing load on your instance.

How this would work:

Now, your admin user can create a user with a minimal amount of data (perhaps just an email address).

The user will, at first login, be prompted to fill out their profile data, including all fields you've marked required.

This is not full progressive registration, but can be useful in certain circumstances.

FusionAuth signs JWTs with a private key it holds. The matching public key is published at the JWKS endpoint (/.well-known/jwks.json). Your mobile app — or any resource server — can verify a token's signature locally, with zero network calls, as long as it has that public key. You can even bundle the public key with the application and avoid the retrieving it.

That's the property that makes offline auth possible. You're not asking "is this token still good?" over the wire; you're asking "did FusionAuth sign this, and has it expired?" using math the device can do on its own.

See JWT signing configuration and the JWKS endpoint docs.

The Flow

1. First login (online, required). The user authenticates against FusionAuth via OAuth with the offline_access scope, or via the Login API with loginId + password + applicationId. You get back two things:

Refresh token details are in the refresh token settings docs.

2. Cache the JWKS on the device. Fetch /.well-known/jwks.json once and store it. You'll match incoming tokens to the right key using the kid in the JWT header. For fully air-gapped scenarios, you can bundle the JWKS into the app at build time — see the air-gapping article.

3. Online operation. The app uses the access token for API calls. When it expires, the app calls the Refresh a JWT API with the refresh token to mint a new access token.

4. Offline operation. The app validates the cached access token locally:

If the token is past exp but the device is offline, allow a bounded grace period (e.g., 24 hours past expiration). After that, degrade functionality until the device reconnects and refreshes. For instance, you could allow read operations but nothing that changes data.

5. On reconnect. Refresh immediately. If the refresh token has been revoked server-side, the call will fail and the user must re-authenticate.

Token lifetime tuning

This is where you make your security/availability tradeoff explicit. FusionAuth lets you tune both lifetimes per tenant or per application:

What FusionAuth gives you for revocation

Refresh tokens can be revoked automatically on password change, MFA enrollment, or any action that prevents login. You can also call the Revoke Refresh Tokens API directly. The catch: revocation only takes effect the next time the device tries to refresh. Already-issued access tokens remain valid until their exp.

Tradeoffs you're signing up for

Be honest with yourself about this approach. These aren't FusionAuth limitations, they're inherent to offline auth:

Practical starting point

Here's an example of the configuration:

Tighten the numbers for higher-sensitivity apps, loosen them for field-work apps where availability matters more than instant revocation.

Some further reading for you:

The short version: FusionAuth gives you all the primitives:

The offline policy is yours to design, and the design is mostly about choosing how much revocation lag you can tolerate in exchange for how much offline runway your users need.

One can have screen_hint=abc on the authorization URL and the other can have screen_hint=def, but both will have all the other parameters the same.

Then you can use an idp_hint on your create or login buttons.

I think that will work, but please let us know.

You can also use a 3 way diffing tool like diff3 or kdiff3 to visualize the changes.

These upgrade notes also provide detailed human friendly instructions on the changes.

From the documentation, the passwordFieldType is the API field to use. This field:

Describes what user.password in the request is. The possible values are:

HASHED - user.password is an already hashed value. When this value is supplied, user.encryptionScheme, user.factor, user.password, and user.salt are required.
PLAINTEXT - user.password is a plain text/unhashed value. FusionAuth will hash this value according to user.encryptionScheme and user.factor.

You want to start by understanding FusionAuth passkey setup and the normal flow.

Then, in your application, probably using one of the client libraries, you want to do the following for a user:

The right way to do the latter depends on your application needs (are you okay with a redirect) and whether or not you have at least a starter license.

For reporting on the number of users that have set up passkeys, unfortunately you have to query all your users and then pull the passkey data individually. There's no way to use the elasticsearch syntax to do the query as of yet. There's an open github issue to add that functionality.

Screenshot 2026-02-18 at 10.43.14 AM.png

Then you should check your Event Log.

Screenshot 2026-02-18 at 10.44.20 AM.png

Let us know what you find.

Apologies for the delayed response. We've done some detailed investigation and can share concrete data.

Environment:

What we observe:

Our deletion job calls the bulk delete API once per user:

DELETE /api/user/bulk?queryString=<email>&hardDelete=true&dryRun=false

On a typical night, 70–210 of these calls are made in rapid succession. A subset fail with:

ERROR io.fusionauth.api.service.search.BaseElasticsearchSearchEngine - Failed to set a Point in Time on index [fusionauth_user]

The response our application receives:

{
"generalErrors": [{"code": "[SearchEngineRequestFailedException]", "message": "A request to the search index has failed. This error is unexpected. Please review the troubleshooting guide..."}],
"status": 503
}

CloudWatch metrics from our OpenSearch domain at the exact moment of failure (29 Jul, 23:12 UTC):

The OpenSearch node is healthy and not under resource pressure. It appears to be actively rejecting the PIT creation request as a client error (4xx), not failing due to overload. The HasUsedPointInTime CloudWatch metric remains 0 throughout, confirming no PIT is ever successfully established.

We don't have visibility into the raw 4xx response body from OpenSearch — FusionAuth wraps it in the generic SearchEngineRequestFailedException. Our OpenSearch application logs only capture JVM-level warnings, and audit logging isn't enabled.

Questions:

Thanks,
Tim