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.

 


• API Authentication

• API Errors

• API Status Codes

• The PATCH HTTP Method

• Exploring The APIs

• Troubleshooting

Here’s a brief video showing how to use an API:

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: application/json

• Actioning Users - These APIs allow you to take actions on Users or modify previous actions (CRUD operations).

• API Keys - These APIs allow you to take actions on API Keys or modify existing API Keys (CRUD operations).

• Applications - These APIs allow you to create, retrieve, update and delete Applications and Application Roles

• Audit Logs - These APIs allow you to create, retrieve, search and export the Audit Log.

• Connectors - These APIs allow you to manage Connectors (CRUD operations).

• Consents - These APIs allow you to manage Consent (CRUD operations).

• Emails - These APIs allow you to both manage Email Templates (CRUD operations) as well as send emails to Users.

• Entities - These APIs allow you to manage Entities (CRUD operations) as well as search and grant permissions to them.

• Entity Types - These APIs allow you to manage Entity Types.

• Event Logs - These APIs allow you to retrieve and search event logs.

• Families - These APIs allow you to manage Families (CRUD operations).

• Forms - These APIs allow you to manage Forms (CRUD operations).

• Form Fields - These APIs allow you to manage Form Fields (CRUD operations).

• Groups - These APIs allow you to manage Groups (CRUD operations) as well Group membership.

• Hosted Backend - These APIs allow you initiate OAuth2 code flow logins with FusionAuth-hosted backend endpoints.

• Identity Providers - These APIs allow you to manage Identity Providers for federating logins.

• Integrations - These APIs allow you to manage FusionAuth integrations such as Kafka, Twilio and CleanSpeak.

• IP Access Control Lists - These APIs allow you to manage IP Access Control Lists.

• JSON Web Tokens - These APIs allow you to manage Refresh Tokens, verify Access Tokens and retrieve public keys used for verifying JWT signatures.

• Keys - These APIs allow you to manage cryptographic keys (CRUD operations).

• Lambdas - These APIs allow you to manage Lambdas (CRUD operations).

• Login - These APIs allow you to authenticate Users.

• Messengers - These APIs allow you to manage Messengers (CRUD operations).

• Multi-Factor - This API allows you to enable and disable Multi-Factor Authentication (MFA) on a user.

• Passwordless - These APIs allow you to authenticate Users without a password.

• Registrations - These APIs allow you to manage the relationship between Users and Applications, also known as Registrations (CRUD operations).

• Reactor - These APIs allow you to manage licensing features.

• Reports - These APIs allow you to retrieve reporting information from FusionAuth.

• SCIM - These APIs allow you to provision users and groups in FusionAuth using SCIM requests from a SCIM Client.

• System - These APIs allow you to retrieve and update the system configuration, export system logs and retrieve system status.

• Tenants - These APIs allow you to manage Tenants (CRUD operations).

• Themes - These APIs allow you to manage Themes (CRUD operations).

• Users - These APIs allow you to create, retrieve, update and delete Users, Search for Users, Bulk Import and Password Management

• User Actions - These APIs allow you to manage User Actions which are the definitions of actions that can be taken on Users (CRUD operations).

• User Action Reasons - These APIs allow you to manage User Action Reasons which are used when you action Users (CRUD operations).

• User Comments - These APIs allow you to retrieve or create comments on Users.

• WebAuthn - These APIs allow you to register, use, and manage WebAuthn passkeys.

• Webhooks - These APIs allow you to manage Webhooks (CRUD operations).

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.

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.

{
  "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"
  }
}

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

{
  "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"
  }
}

{
  "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"
  }
}

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

{
  "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"
  }
}

{
  "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"
  }
}

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

{
  "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:

• Authorization: the API key in most cases. Review the API Authentication documentation for more information.

• Content-type: this is almost always application/json for any call which is not a GET request. This header can be omitted for a GET request. If you don’t specify this header when making a non-GET API call, you will see an unexpected error.

• X-FusionAuth-TenantId: only required when you have two or more tenants and the tenant cannot be inferred from the request or API key. However, you can always provide this header.

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.