Load testing FusionAuth typically involves using a modern tool like k6 to simulate your expected traffic patterns. Here's the general approach:

1. Use k6 or other HTTP-capable load testing tools: While k6 is a good modern option, FusionAuth can be load tested with any HTTP-capable load testing tool such as Gatling, JMeter, or Locust. FusionAuth also provides an open source load testing repository with pre-built scenarios including creating tenants and applications, registering users, logging users in via the Login API, and full Authorization Code grant flows.

2. Profile your traffic: Use your load testing tool to determine what your actual traffic patterns will look like, especially accounting for your spiky demand. This helps you understand the load FusionAuth will need to handle. Look beyond just averages—also check the p95 (95th percentile) response time to understand the experience of your slowest users.

3. Test in a production-like environment: It's critical to load test against an environment that mirrors your expected production setup. If you're using FusionAuth Cloud, the Basic Cloud tier (single node running FusionAuth, Elasticsearch, and PostgreSQL together) is not representative and not recommended for load testing. Instead, use a Business Cloud or High-Availability plan for meaningful load testing. You can spin up an HA instance, run your tests, and tear it down—you'll only be charged for the time it's running.

4. Notify FusionAuth if testing on Cloud: If you're load testing on FusionAuth Cloud, open a support ticket to let the team know when you plan to stress test, as they monitor CPU and other metrics.

5. Monitor the right components: Performance bottlenecks are typically the database or CPU nodes. Both logins and user creation are CPU-intensive due to password hashing. If testing a multi-node system behind a load balancer, disable sticky sessions as they are not required for FusionAuth.

6. IP allowlisting considerations: If you're using FusionAuth Cloud, you may need to consider IP allowlisting depending on your security configuration. FusionAuth Cloud has protections in place to prevent DoS attacks and keep services running smoothly.

The specific approach can vary based on your exact traffic patterns and requirements, but these are the key components most customers use when load testing FusionAuth.

Related Documentation

• Load Test Documentation - Comprehensive guide on load testing FusionAuth, including tool recommendations and best practices
• FusionAuth Load Tests GitHub Repository - Open source load testing scripts with pre-built scenarios
• Handling Spiky Game Traffic: Registration & Autoscaling Best Practices - Specific guidance for handling spiky traffic patterns during high-demand scenarios
• FusionAuth Cloud High Availability Architecture - Details on HA deployment options for production-like testing
• FusionAuth Cloud Security - Information about Cloud security protections and rate limiting
• Troubleshooting Performance - Guide for troubleshooting performance issues
• Scaling Your Auth - Best Practices for Performance and Security - General guidance on scaling authentication systems

We need to include FusionAuth in our regular performance testing to handle very spiky demand patterns in our application. This is a requirement before we can scale up in production and will be an ongoing need. What guidance can you provide on how to best approach load testing FusionAuth in our test environments?

Yes, you can use your FusionAuth licenses across multiple environments, but you should use the appropriate license type for each:

License Structure

In your account portal at account.fusionauth.io, you should see two licenses:

1. Production License — use this for your production environment only
2. Non-Production License — use this for your dev and staging environments

Best Practice

• Deploy the Non-Production license to your dev and staging instances
• Deploy the Production license to your production instance

Both licenses can be active simultaneously across different deployments without conflict. The license key itself is tied to your account and does not interfere with your managed FusionAuth Cloud setup when used in self-hosted deployments.

Important Notes

• The non-production license can be used across as many non-production environments as you need — dev, staging, QA, UAT, CI/CD, or even individual developer local instances. There's no limit on the number of instances using the non-production key.

• Do not use the production license on non-production environments — this would cause test logins to count toward your Monthly Active Users (MAU) and affect your billing.

• License costs are not based on the number of instances — whether you have 1, 2, or 100 instances, the license cost is related only to your plan tier and MAU count.

• Using self-hosted licenses won't affect your FusionAuth Cloud deployment — the licenses operate independently, so activating your license keys on self-hosted instances will not disrupt your existing managed environment.

Related Documentation

• Licensing Documentation — Overview of FusionAuth licensing concepts
• License FAQ: Non-Production Licenses — Details on using licenses for dev/QA/UAT servers
• License FAQ: Multiple Deployments — How license costs work with multiple instances
• Account Portal Documentation — Where to find your license keys
• Cloud vs Self-Hosted — Comparison of hosting options

I am migrating from FusionAuth Cloud to a self-hosted deployment. I have successfully set up a new cluster and imported the database from the managed environment.

In the self-hosted FusionAuth instance, I see an option to add a license key. When I check my account portal at account.fusionauth.io, I see a primary license key.

Questions:

• Can I use this same license key in parallel across multiple environments (dev, staging, production)?
• Will using the key in my self-hosted deployment impact or conflict with the existing managed FusionAuth setup?

I want to ensure I don't accidentally disrupt the current managed environment while setting up the new self-hosted instances.

The act claim was reserved in FusionAuth 1.70.0 because it is defined in RFC 8693 (OAuth 2.0 Token Exchange) as a standard claim representing the "actor" in delegated token scenarios. FusionAuth began enforcing this reservation to ensure compliance with the RFC and prevent conflicts with the claim's intended usage in token exchange flows.

Why This Is Classified as Minor

FusionAuth follows semantic versioning, and this change was classified as minor rather than breaking because:

• The act claim is a standardized RFC claim with a specific defined purpose
• Using non-standard values in RFC-defined claims can cause interoperability issues with other OAuth/OIDC systems
• The change aligns FusionAuth's behavior with industry standards

However, the lack of logging when a reserved claim is silently discarded is a valid concern and makes troubleshooting difficult.

Recommended Solutions

1. Use a Custom Claim Namespace

Instead of using act directly, use a namespaced custom claim that won't conflict with RFC-defined claims:

// In your JWT populate lambda
jwt['https://yourapp.com/actor'] = 'your-actor-id';

This approach is standard practice in OAuth/OIDC and prevents future collisions with reserved claims.

2. Use applicationId or Other Non-Reserved Claims

If the actor represents an application or service account, consider using the built-in applicationId claim or another custom claim that describes your specific use case (e.g., actorId, serviceAccountId).

Why Reserved Claims Cannot Be Overridden

Reserved claims like act, sub, iss, aud, etc., are protected because they have specific meanings defined by RFCs and must maintain consistent behavior for:

• Interoperability: Other systems expect these claims to have specific formats and meanings
• Security: Claims like iss and aud are critical for token validation and cannot be arbitrarily changed
• Standards Compliance: FusionAuth aims to be a standards-compliant identity provider

Migration Path

If you're currently using act in production:

1. Update your JWT populate lambda to use a namespaced custom claim
2. Update your application to read from the new claim name
3. Test thoroughly in a non-production environment before upgrading

If you need to maintain backward compatibility during migration, you could temporarily set both claims in your lambda (the custom namespaced one and attempt to set act, knowing it will be discarded) and update your application to check for both, prioritizing the custom claim.

---

Related Documentation

• JWT Populate Lambda - Documentation on customizing JWT claims with lambdas
• Client Credentials JWT Populate Lambda - Documentation for lambdas in the Client Credentials grant
• OAuth Token Exchange (RFC 8693) - FusionAuth's implementation of RFC 8693, which defines the act claim
• FusionAuth 1.70.0 Release Notes - Release notes for version 1.70.0
• FusionAuth 1.70 Announcement: Token Exchange - Blog post explaining the new token exchange feature and scoped delegation
• GitHub Issue #1721: JWT claim overriding, namespacing or the ability to unreserve claims - Open issue discussing the ability to override or unreserve claims

Additional Context on Reserved Claims

As of FusionAuth 1.70.0, the following claims are reserved in JWT Populate Lambdas and cannot be modified:

• act (added in 1.70.0)
• amr
• auth_time
• authenticationType
• cnf
• fa_uid
• gty
• iat
• sub
• tid
• tty

Note: The exp claim can be lowered (shortened) but not extended or removed.

For other lambda types (Client Credentials, UserInfo, Token Exchange), different sets of reserved claims apply. Always use namespaced custom claims (e.g., https://example.com/my-claim) to avoid conflicts with current or future reserved claims.

After upgrading to FusionAuth 1.70.0, a JWT populate lambda that was previously setting the act claim now silently fails. The lambda executes successfully, but the act claim is discarded without any warning or error log.

The application had been using act to represent the actor while maintaining internal user IDs (since sub cannot be overridden). This worked fine in earlier versions, but after upgrading to 1.70.0, the claim is no longer present in the JWT, breaking authentication.

Questions:

1. Why was act made a reserved claim in 1.70.0?
2. Is there any way to override reserved claims or disable this behavior?
3. Why is there no warning log when FusionAuth discards a reserved claim set by a lambda?
4. How is this considered a minor change rather than a breaking change when it silently breaks existing implementations?

This pattern seems risky — any claim name in use today could become reserved in a future RFC, causing working implementations to fail after an upgrade with no visibility into what changed.

This is a confirmed bug in FusionAuth 1.69.2. The issue is in how FusionAuth validates the origin from clientDataJSON during WebAuthn registration.

This has been fixed and will be released in the next release. Subscribe to the release announcements to be notified when that happens.

After upgrading FusionAuth from 1.55.x to 1.69.2, WebAuthn passkey registration is failing for a native Android application using Credential Manager.

Setup

• FusionAuth Server: 1.69.2
• WebAuthn workflow: reauthentication
• Relying Party ID: a web domain (e.g., dashboard.example.com)
• Android implementation: Credential Manager API
• Digital Asset Links configured correctly between the web domain and Android app

The Problem

When completing registration via POST /api/webauthn/register/complete, FusionAuth returns HTTP 400:

{
  "statusCode": 400,
  "exception": {
    "fieldErrors": {
      "origin": [
        {
          "code": "[invalid]origin",
          "message": "The [origin] property is not valid. The provided value must match the value returned by the authenticator. Expected [android:apk-key-hash:<certificate-hash>] but found [dashboard.example.com]."
        }
      ]
    }
  }
}

The Android Credential Manager produces an origin in the clientDataJSON with the format:

android:apk-key-hash:<base64url-sha256-of-signing-certificate>

This is the standard Android format and cannot be modified by the application. FusionAuth 1.69.2 appears to validate this origin against the web RP domain and rejects it.

What Changed

Before 1.69.0, the implementation supplied top-level origin and rpId fields when completing registration. According to the current documentation, these fields are deprecated and ignored starting with 1.69.0. The new implementation now passes only:

await fusionAuthClient.completeWebAuthnRegistration({
  userId,
  credential,
});

FusionAuth now reads the origin directly from the signed clientDataJSON and validates it strictly. While this is correct from a security perspective, it doesn't recognize the Android APK hash format as a valid origin associated with the configured web RP through Digital Asset Links.

Questions

1. Does FusionAuth 1.69.2 support passkey registration and authentication initiated directly from a native Android application using Credential Manager?
2. Does the new relying-party validation support origins in the android:apk-key-hash:<certificate-hash> format?
3. Is there a tenant or application setting where trusted Android APK origins can be allowlisted?
4. Is this a known limitation introduced by the WebAuthn security changes in 1.69.0?
5. Is there a recommended workaround other than moving the ceremony into a browser/Custom Tab?

The data sub-object containing auth_time and authentication_type in refresh token metadata is not currently a documented or officially supported feature in FusionAuth. Its presence is inconsistent across authentication flows, as you've observed — it appears for some authentication types but not others (notably absent for MFA + PASSWORD flows).

According to the official documentation, the only documented fields within refresh token metaData are:

• metaData.device — An object containing device information (name, type, description, lastAccessedAddress, lastAccessedInstant)
• metaData.scopes — An array of OAuth scopes associated with the token
• metaData.resources — An array of resource URIs per RFC 8707 (available since v1.67.0)

The data sub-object with auth_time and authentication_type that you're observing is not part of the documented API contract. Because this is undocumented behavior, you should not rely on it in production code, as it may change or be removed in future versions without notice.

Important Distinction: auth_time on JWTs vs Refresh Tokens

Note that auth_time is a standard and documented claim on access tokens and ID tokens (the JWTs themselves), where it represents the time of initial authentication. However, it is not a documented field on the refresh token record itself when queried via the retrieval API.

Related Documentation

• Retrieve Refresh Tokens API — Official API documentation including the complete response body structure for refresh tokens
• Access Token and ID Token Claims — Where auth_time is officially documented as a JWT claim
• Multi-Factor Authentication (MFA) — Guide to implementing MFA in FusionAuth
• JWT Refresh API — How to use refresh tokens to obtain new access tokens

When querying the refresh token endpoint GET /api/jwt/refresh?userId={userId}, some refresh tokens include a data sub-object under metaData containing fields like auth_time and authentication_type.

This metadata appears to be present for the following authentication types:

• PASSWORD
• PASSWORDLESS
• SAMLv2IdpInitiated
• SAMLv2

However, when users authenticate using MFA + PASSWORD, the data sub-object is missing from the refresh token metadata.

Is this data object (specifically auth_time and authentication_type) something that can be reliably used across all authentication flows in current and future versions of FusionAuth? Or is its presence inconsistent and not intended as a stable API feature?