API Overview

Overview

The core of FusionAuth is a set of RESTful APIs that allow you to quickly integrate login, registration and advanced User management features into your application. The FusionAuth web UI is built upon these APIs. Everything in the user interface is available through an API.

On this page you will find links to each of the API groups and a general overview of the API status codes you can expect back from each API. Each API will also document specific status codes and the specific meaning of the status code.

APIs

Unless stated otherwise, all of the FusionAuth APIs will expect to receive a JSON request body. Ensure you have added the Content-Type HTTP header to your request.

Content-Type Header

Content-Type: application/json

The APIs are grouped into the following categories.

Note: Null values in JSON are not allowed on any of the FusionAuth APIs. If you are looking to pass in a null value, simply omit it from your request instead. This will allow FusionAuth to handle default values correctly.

Status Codes

Each API may document specific status codes and provide a specific reason for returning that status code. This is a general overview of the status codes you may expect from an API and what they will mean to you.

Response Codes

CodeDescription
200The request was successful. Generally the response body will contain JSON unless documented otherwise.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401The request authentication failed. This request requires authentication and the API key was either omitted or invalid. In some cases this may also be returned if you are not authorized to make the request. See Authentication for additional information on API authentication.
404The object you requested doesn’t exist. The response will be empty.
405The HTTP method you requested is not allowed for the URI. This is a user error in making the HTTP request to the API. For example, if POST is the only supported way to call a particular API and you make the HTTP request with GET, you will receive a 405 status code. No body will be returned.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. This is generally a FusionAuth error condition. If possible open a GitHub Issue so we can help you resolve the issue.
501The HTTP method you requested is not implemented. This is a user error in making the HTTP request to the API.
503The requested action cannot be completed due the current rate of requests. Retry the request later.
512A lambda invocation failed during this API request. An event log will have been created with details of the exception. See System -> Event Log.

The PATCH HTTP Method

There are three options for using PATCH operations. You choose between them by specifying a particular Content-Type on the request.

PATCH options

NameContent-TypeArray BehaviorAvailable SinceRFC LinkClient Library SupportNotes
Originalapplication/jsonVaries, sometimes a merge, other times an append. Read the documentation and test before using. Safest option is GET then PUT.1.12.0N/AYesMay be deprecated in the future.
JSON Patchapplication/json-patch+jsonUses operations to specify JSON modifications.1.39.0RFC 6902NoUseful patch builder tool
JSON Merge Patchapplication/merge-patch+jsonIf target value is an array, overwrite the existing value with what is provided.1.39.0RFC 7396NoN/A

PATCH Example

Here’s an example of how the different options work when used to modify the roles of a Group which has roles of “ceo” and “dev” to remove the “dev” role.

If you are only modifying specific object fields, all three PATCH methods are equivalent.

Original

With the original, pre 1.39.0 PATCH method, the correct way to remove the “dev” role is to request the group JSON, find the “ceo” role from the roleIds array, and use PUT to update the group object.

Original Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663971044647,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        },
        {
          "id": "52fc8fe4-0afb-4040-903c-234e20271cf6",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "dev"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

PUT Request JSON

{
  "group": {
    "name": "Paid employees",
    "data": {}
  },
  "roleIds": [
    "0a15cfdd-e231-4de4-9411-6d1015e05d99"
  ]
}

After you make this PUT request, the group JSON will look like this.

Resulting Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663972082307,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

JSON Patch

With JSON Patch, you have a flexible set of operations that can update, remove or move fields in a JSON object. Please review RFC 6902 for the full list of operations. Here’s the original JSON again:

Original Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663971044647,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        },
        {
          "id": "52fc8fe4-0afb-4040-903c-234e20271cf6",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "dev"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

If you make a PATCH request with a Content-Type of application/json-patch+json and a body like below:

JSON Patch Request JSON

[
  {
    "op": "remove",
    "path": "/roleIds/1"
  }
]

This call removes the second value of the roleIds array, which corresponds to the “devs” role. You’ll need to find what array element you want to delete, perhaps with a separate request. After you make this PATCH request, the group JSON will look like this.

Resulting Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663972082307,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

This approach is precise and can make multiple changes to a given object with one call. It also requires you to learn a new set of operations. Additionally, the data is sent in format (an array of operations) which is only vaguely related to the structure of the object being changed.

JSON Merge Patch

JSON Merge Patch is a more straightforward way to update complex JSON objects. Please review RFC 7386 for a full description of the patch behavior. Here’s the original JSON again:

Original Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663971044647,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        },
        {
          "id": "52fc8fe4-0afb-4040-903c-234e20271cf6",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "dev"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

If you make a PATCH request with a Content-Type of application/merge-patch+json and a body like below:

JSON Patch Request JSON

{
  "roleIds": [
    "0a15cfdd-e231-4de4-9411-6d1015e05d99"
  ]
}

After you make this PATCH request, the group JSON will look like this.

Resulting Group JSON
{
  "group": {
    "data": {},
    "id": "88c5ab6b-f3ea-4d37-91eb-1261d9cd7b07",
    "insertInstant": 1663971044647,
    "lastUpdateInstant": 1663972082307,
    "name": "Paid employees",
    "roles": {
      "85a03867-dccf-4882-adde-1a79aeec50df": [
        {
          "id": "0a15cfdd-e231-4de4-9411-6d1015e05d99",
          "insertInstant": 1663701174145,
          "isDefault": false,
          "isSuperRole": false,
          "lastUpdateInstant": 1663701174145,
          "name": "ceo"
        }
      ]
    },
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

Exploring The APIs

You can explore our APIs using a self hosted instance, one you run yourself on a remote server, or using the Sandbox.

You can use our API explorer or our Postman collection.

Troubleshooting

When your API call isn’t working, taking the following steps can help you troubleshoot it.

Use the REST API directly. While the client libraries are useful abstractions, removing them helps narrow down the issues. Curl or wget are great choices.

When using a command line tool like curl, make sure you set the headers appropriately. These headers are commonly forgotten:

Additionally, it can be helpful to copy and paste the JSON body from the documentation for the call you are trying to debug.

If you are seeing a 401 error, confirm that the API key has the required permissions. Test with a ‘super user’ key to ensure you have the headers and body correct.

Ensure you are making requests to the correct host and that your proxy, if using one, passes API requests correctly. When troubleshooting, call the FusionAuth instance directly if possible. This removes the proxy, yet another possible source of issues.

401s With New API Keys

FusionAuth caches API keys for a faster lookup. There is an internal distributed cache and notification policy for multi-node deployments. When you create a new key, it will take time for the API key to be usable. Usually this less than one second. In rare cases where node communication fails, it may take up to 60 seconds.

This means that if you create a new API key using the API Key API and use it immediately, you may receive a 401 status code. This typically indicates you didn’t supply a valid API key, but in this case means that the new key is not yet usable.

The workaround to wait for a period, using exponential backoff and then retry the request.