/ Docs

Test

Available since version 1.65.0

The Identity Provider connection testing API allows you to test an Identity Provider connection, even when disabled, to ensure that the configuration is correct and that FusionAuth can connect to the 3rd party provider. This API is useful for troubleshooting connectivity issues with an Identity Provider.

This API does not create or update users or registrations, or generate an authorization code or tokens.

Start an Identity Provider Connection Test#

Request#

API Key Authentication
Start an Identity Provider Connection Test for a given IdP and Tenant
POST /api/identity-provider/test

Request Body

identityProviderIdUUIDrequired
The unique Id of the Identity Provider configuration to be tested.
tenantIdUUIDrequired
The unique Id of the Tenant to use for this test. This field is required.

Example Identity Provider Test Request JSON

{
  "identityProviderId": "4d3f5f7d-8e89-4c06-9d2b-8fbf8cdbb123",
  "tenantId": "9e8f88c4-9f89-49f2-9db5-6cbf6f4f9abc"
}

Response#

Response Codes
Code Description
200 The request was successful. The response will contain a JSON body.
400 The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401 You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500 There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

connectionTestIdString

The unique Id of the identity provider connection test that was executed.

Example Identity Provider Test Response JSON

{
  "connectionTestId": "f1e2d3c4-b5a6-47a8-9012-3456789abcde"
}

The returned connectionTestId is temporary and expires after the Tenant-configured external identifier TTL. Configure this value using tenant.externalIdentifierConfiguration.identityProviderConnectionTestTimeToLiveInSeconds (default 1800 seconds).

Retrieve Identity Provider Connection Test Results#

Request#

API Key Authentication
Retrieve Identity Provider Connection Test Results
GET /api/identity-provider/test?connectionTestId={connectionTestId}

Request Parameters#

connectionTestIdStringrequired

The connection test Id returned by the Start Identity Provider Connection Test API.

Response#

Response Codes
Code Description
200 The request was successful. The response will contain a JSON body.
400 The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401 You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404 The object you requested doesn't exist. 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.

Response Body

result.successBoolean

Whether the test completed successfully. This is true only when at least one step exists and all recorded steps succeeded.

result.startInstantDateTime

The instant at which the test began.

result.identityProviderIdUUID

The Identity Provider Id used for the test.

result.identityProviderUserIdString

The third-party user Id resolved during the test, if available.

result.emailString

The reconciled email address, if available.

result.usernameString

The reconciled username, if available.

result.stepsArray<Object>

Ordered trace steps captured during the connection test.

result.steps[].titleString

The step title.

result.steps[].successBoolean

Whether the step succeeded.

result.steps[].detailString

Additional detail for the step.

Example Identity Provider Test Results Response JSON

{
  "result": {
    "success": true,
    "startInstant": "2026-04-21T15:04:05.123Z",
    "identityProviderId": "4d3f5f7d-8e89-4c06-9d2b-8fbf8cdbb123",
    "identityProviderUserId": "41",
    "email": "example@fusionauth.io",
    "username": "example",
    "steps": [
      {
        "title": "Success",
        "success": true,
        "detail": "The identity provider login successfully reconciled a user."
      }
    ]
  }
}