FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

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

     
    The APIs are grouped into the following categories.

    • 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.

    • 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).

    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.

    Table 1. Response Codes
    Code Description

    200

    The request was successful. Generally the response body will contain JSON unless documented otherwise.

    400

    The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

    401

    The 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.

    404

    The object you requested doesn’t exist. The response will be empty.

    405

    The 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.

    500

    There 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.

    501

    The HTTP method you requested is not implemented. This is a user error in making the HTTP request to the API.

    503

    The requested action cannot be completed due the current rate of requests. Retry the request later.

    512

    A 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.

    Table 2. PATCH options
    Name Content-Type Array Behavior Available Since RFC Link Client Library Support Notes

    Original

    application/json

    Varies, sometimes a merge, other times an append. Read the documentation and test before using. Safest option is GET then PUT.

    1.12.0

    N/A

    Yes

    May be deprecated in the future.

    JSON Patch

    application/json-patch+json

    Uses operations to specify JSON modifications.

    1.39.0

    RFC 6902

    No

    Useful patch builder tool

    JSON Merge Patch

    application/merge-patch+json

    If target value is an array, overwrite the existing value with what is provided.

    1.39.0

    RFC 7396

    No

    N/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:

    • 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.

    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates