> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Reconcile a JWT Using the External JWT Provider API documentation for the FusionAuth Reconcile a JWT Using the External JWT Provider API. # Reconcile a JWT Using the External JWT Provider The Reconcile API is used to take a JWT issued by a third party identity provider as described by an [External JWT Identity Provider](https://fusionauth.io/docs/apis/identity-providers/external-jwt.md) configuration and reconcile the User represented by the JWT to FusionAuth. caution This external JWT Identity Provider flow is not compatible with the hosted login pages. This integration is accessible through our API only. Additionally, if you are integrating with any of the identity providers for which there is a provided Identity Provider integration (whether specific like Facebook or generic like OIDC), prefer those options over this provider. In general, you should use the `/api/identity-provider/login` endpoint of another Identity Provider rather than the External JWT provider if one is available. ## Request [!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required) Reconcile a JWT POST/api/jwt/reconcile OpenAPI Spec ### Request Headers `X-Forwarded-For`Stringoptional The IP address of a client requesting authentication. If the IP address is provided it will be stored for login history of the user. It is generally preferred to specify the IP address in the request body. If it is not provided in the request body this header value will be used if available, the request body value will take precedence. `X-FusionAuth-TenantId`Stringoptional The unique Id of the tenant used to scope this API request. The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required. Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result. See [Making an API request using a Tenant Id](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Body `applicationId`UUIDrequired The Id of the Application the User will be logged into during the reconcile process. If the User is not already registered to this Application they will be registered and be assigned any roles identified as default. If this value is not a valid Application Id, a `401` will be returned. `encodedJWT`StringrequiredDEPRECATED The encoded JWT issued by a third party Identity Provider. Once available use the `data.token` parameter instead. `data.token`StringrequiredAvailable since 1.1.0 The encoded JWT issued by a third party Identity Provider. `identityProviderId`UUIDrequired The unique Id of the Identity Provider to utilize when reconciling the JWT. If this value is not a valid Identity Provider Id, a `401` will be returned. `ipAddress`Stringoptional The IP address of the end-user that is logging into FusionAuth. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. The IP address will be stored in the User login history. `metaData.device.description`Stringoptional A human readable description of the device represented by the `device` parameter. `metaData.device.lastAccessedAddress`Stringoptional The IP address of this login request. `metaData.device.name`Stringoptional A human readable name of the device represented by the `device` parameter. `metaData.device.type`Stringoptional The type of device represented by the `device` parameter. Prior to version 1.46.0, this value was restricted to the following types: * `BROWSER` * `DESKTOP` * `LAPTOP` * `MOBILE` * `OTHER` * `SERVER` * `TABLET` * `TV` * `UNKNOWN` In version `1.46.0` and beyond, this value can be any string value you'd like, have fun with it! *Example Request JSON* ```json { "applicationId": "ff9880a1-74fd-4947-b482-1ca6f9788362", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo" }, "identityProviderId": "0c5ecd6e-a55f-4d3c-8236-f26a966392ea", "ipAddress": "192.168.1.42" } ``` ## Response The response for this API contains the User object. *Response Codes* | Code | Description | | --- | --- | | 200 | The reconcile was successful. The response will contain the User object that was authenticated. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. | | 401 | The request cannot be completed. The `identityProviderId` is invalid, the JWT signature cannot be validated, the JWT does not contain a claim identified by the `uniqueIdentityClaim` property in the Identity Provider configuration, or the domain of the email address claim in the JWT is not managed by the Identity Provider Configuration. | | 404 | The user was not found or the password was incorrect. The response will be empty. | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | #### Response Body `emailVerificationId`String An email verification Id, which is needed when performing your own email verification using the `/api/user/verify-email` API. This field is only returned when the **tenant.emailConfiguration.verificationStrategy** is set to `FormField`. `identityVerificationId`StringAvailable since 1.59.0 An identity verification Id, which is needed when performing your own identity verification using the `/api/identity/verify` API. This field is only returned under the following conditions, based on the identity that was used to log in: * An email address - the **tenant.emailConfiguration.verificationStrategy** is set to `FormField`. * A phone number - the **tenant.phoneConfiguration.verificationStrategy** is set to `FormField`. `refreshToken`String The refresh token that can be used to obtain a new access token once the provided one has expired. Because a refresh token is per user and per application, this value will only be returned when an **applicationId** was provided on the login request and the user is registered to the application. You must explicitly allow generation of refresh tokens when using the Login API. Configure the **application.loginConfiguration.generateRefreshTokens** setting via the API or enable the setting by navigating to the Application -> My Application -> Security tab. `refreshTokenId`StringAvailable since 1.37.0 When the **refreshToken** is returned in the response, this field will also be returned. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the [Refresh Token API](https://fusionauth.io/docs/apis/jwt/revoke-refresh-tokens.md). `state`Object If authenticated using a One Time Password and **state** was provided during the Change Password request this value will be returned exactly as it was provided. `token`StringAvailable since 1.16.0 The access token, this string is an encoded JSON Web Token (JWT). When the user will be sent a setup password email or sms message, this token will not be returned. `tokenExpirationInstant`LongAvailable since 1.33.0 The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) the **token** will expire. If the response does not contain a **token**, this field will also be omitted from the response. `user.active`Boolean True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to log in. `user.birthDate`String The User's birthdate formatted as `YYYY-MM-DD` `user.breachedPasswordLastCheckedInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) this user's password was last checked to determine if it is compromised. `user.connectorId`UUIDAvailable since 1.18.0 The unique Id of the [Connector](https://fusionauth.io/docs/lifecycle/migrate-users/connectors.md) associated with the System of Record being used to authenticate the user. `user.cleanSpeakId`UUID This Id is used by FusionAuth when the User's username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the **content Id** of the username inside CleanSpeak. `user.data`Object An object that can hold any information about the User that should be persisted. `user.data.email`String This field will be used as the email address if no **user.email** field is found. This feature was removed in version 1.26.0 and added back in 1.27.2. `user.email`String The User's email address. `user.expiry`Long The expiration [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of the User's account. An expired user is not permitted to log in. `user.firstName`String The first name of the User. `user.fullName`String The User's full name as a separate field that is not calculated from **firstName** and **lastName**. `user.id`UUID The User's unique Id. `user.identities`ArrayAvailable since 1.59.0 The list of identities that exist for a User. `user.identities[x].displayValue`StringAvailable since 1.59.0 The display value for the identity. Only used for `username` type identities. If the unique username feature is not enabled, this value will be the same as **user.identities\[x\].value**. Otherwise, it will be the username the User has chosen. For primary username identities, this will be the same value as **user.username**. `user.identities[x].insertInstant`LongAvailable since 1.59.0 The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity was created. `user.identities[x].lastLoginInstant`LongAvailable since 1.59.0 The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity was last used to log in. If a User has multiple identity types (`username`, `email`, and `phoneNumber`), then this value will represent the specific identity they last used to log in. This contrasts with **user.lastLoginInstant**, which represents the last time any of the User's identities was used to log in. note Identity provider logins will not be reflected here (see **user.lastLoginInstant** for a field that includes identity provider logins). `user.identities[x].lastUpdateInstant`LongAvailable since 1.59.0 The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity was last updated. `user.identities[x].moderationStatus`StringAvailable since 1.59.0 The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are: * `ACTIVE` - the username is active * `PENDING` - the username is pending approval/moderation * `REJECTED` - the username was rejected during moderation If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again. Only used for `username` type identities. For primary username identities, this will be the same value as **user.usernameStatus**. `user.identities[x].type`StringAvailable since 1.59.0 The identity type. The possible values are: * `email` - identities defined by an email address * `phoneNumber` - identities defined by a phone number * `username` - identities defined by a username `user.identities[x].value`StringAvailable since 1.59.0 The value represented by the identity. The contents of this field depend on **user.identities\[x\].type**and will be one of the following: * Email address - The User's email address, always lower cased. For primary email identities, this will be the same value as **user.email** * Phone number - The User's phone number, in E.164 canonical format. For primary phone number identities, this will be the same value as **user.phoneNumber** * Username - User's username - this will be the same as **user.identities\[x\].displayValue**. For primary username identities, this will be the same value as **user.username** This value is unique within a tenant for a particular **user.identities\[x\].type**. note If the unique usernames feature is enabled, `value` will be the unique username (within the tenant). For primary username identities, this will also be the same value as **user.uniqueUsername**. `user.identities[x].verified`BooleanAvailable since 1.59.0 Whether verification was actually performed on the identity by FusionAuth. This is used in combination with the **user.identities\[x\].verifiedReason** to decide whether an identity needs verification. `user.identities[x].verifiedInstant`LongAvailable since 1.59.0 The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when verification was performed on the identity. This field is only populated when verification was actually performed on the identity by FusionAuth. `user.identities[x].verifiedReason`StringAvailable since 1.59.0 The reason the User's identity was verified or not verified. The possible values are: * `Skipped` - Verification was skipped due to the `skipVerification` parameter on the request * `Trusted` - Identity was created via an identity provider or a connector * `Unverifiable` - FusionAuth doesn't know how to verify this identity type. Usernames are an example * `Implicit` - Verification was implicitly performed by sending a set password or passwordless message * `Pending` - Tenant policy requires verification but no verification has been performed yet * `Completed` - Verification was performed by FusionAuth * `Disabled` - Tenant policy did not require verification * `Import` - User was imported so verification was not performed by FusionAuth If this field is `Disabled`, `Import`, `Skipped`, `Trusted`, or `Unverifiable`, then verification will not be required, regardless of the **user.identities\[x\].verified** value. For `Implicit`, `Pending`, or `Completed`, the identity will require verification if **user.identities\[x\].verified** is false. `user.imageUrl`String The URL that points to an image file that is the User's profile image. `user.insertInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the user was created. `user.lastLoginInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the User logged in last. See **user.identities\[x\].lastLoginInstant** for more granular information based on identity. `user.lastName`String The User's last name. `user.lastUpdateInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the User was last updated. `user.legacyIdentifier`StringAvailable since 1.67 Used to override the `sub` claim in tokens issued by the Legacy Identity Provider Adapter. This value is immutable after the user is created and is unique within the tenant when non-null. `user.memberships`Array The list of memberships for the User. `user.memberships[x].data`Object An object that can hold any information about the User for this membership that should be persisted. `user.memberships[x].groupId`UUID The Id of the Group of this membership. `user.memberships[x].id`UUID The unique Id of this membership. `user.memberships[x].insertInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the membership was created. `user.middleName`String The User's middle name. `user.mobilePhone`String The User's mobile phone number. This is useful if you will be sending push notifications or SMS messages to the User. note This differs from **user.phoneNumber** and cannot be used to log in. `user.parentEmail`StringAvailable since 1.7.0 The email address of the user's parent or guardian. If this value was provided during a create or update operation, this value will only remain until the child is claimed by a parent. `user.passwordChangeRequired`Boolean Indicates that the User's password needs to be changed during their next login attempt. `user.passwordLastUpdateInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the User last changed their password. note Since version 1.59.0, if a user does not currently have a password, this field will not be returned in the response. `user.phoneNumber`StringAvailable since 1.59.0 The User's primary phone number. The phone number is stored and returned in E.164 canonical format, however a phone number is considered unique regardless of the format. `303-555-1212` is considered equal to `+13035551212` so either version of this phone number can be used whenever providing it as input to an API. note This differs from **user.mobilePhone** in that **user.phoneNumber** can be used to log in, just like an email address or a username. `user.preferredLanguages`Array An array of locale strings that give, in order, the User's preferred languages. These are important for email templates and other localizable text. See [Locales](https://fusionauth.io/docs/reference/data-types.md#locales). `user.registrations`Array The list of registrations for the User. This will include registrations for inactive applications. `user.registrations[x].applicationId`UUID The Id of the Application that this registration is for. `user.registrations[x].authenticationToken`String The Authentication Token for this registration (if one exists). `user.registrations[x].cleanSpeakId`UUID This Id is used by FusionAuth when the User's username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the **content Id** of the username inside CleanSpeak. `user.registrations[x].data`Object An object that can hold any information about the User for this registration that should be persisted. `user.registrations[x].id`UUID The Id of this registration. `user.registrations[x].insertInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this registration was created. `user.registrations[x].lastLoginInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the User last logged into the Application for this registration. `user.registrations[x].preferredLanguages`Array An array of locale strings that give, in order, the User's preferred languages for this registration. These are important for email templates and other localizable text. `user.registrations[x].roles`Array The list of roles that the User has for this registration. The string is the role's `Name` not the role's `Id`, e.g. `admin` or `user-role`. `user.registrations[x].timezone`String The User's preferred timezone for this registration. The string will be in an [IANA](https://www.iana.org/time-zones) time zone format. `user.registrations[x].tokens`Map