API Authentication
Overview
The FusionAuth APIs are primarily secured using API keys. A few APIs may use alternate credentials, such as a JWT, basic authentication. Certain APIs are accessible with no authentication. All secured APIs will return an 401 Unauthorized
response if improper credentials are provided.
Each API endpoint is marked with an icon describing supported authentication methods:
You can also learn about:
Below you will find a detailed explanation of each type of authentication used in the API documentation.
API Key Authentication
When an API is marked with a red locked icon such as it means you are required to provide an API key.
To enable access to a secured API create one or more API keys. The API key is then supplied in the HTTP request using the Authorization header. See Managing API Keys for more information on adding additional keys.
The following example demonstrates the HTTP Authorization header with an API key of 2524a832-c1c6-4894-9125-41a9ea84e013
.
Authorization: 2524a832-c1c6-4894-9125-41a9ea84e013
The following is a curl example using the Authorization header using the above API key to retrieve a user. The line breaks and spaces are for readability.
curl -H 'Authorization: 2524a832-c1c6-4894-9125-41a9ea84e013' \
'https://local.fusionauth.io/api/user?email=richard@piedpiper.com'
Here’s a brief video covering some aspects of API keys:
Basic Authentication using an API Key
This authentication method has been available since 1.27.0
When an API endpoint is marked with a shield such as it means you call this API and authenticate using HTTP basic authentication. HTTP basic authentication is a simple, standards based, authentication method. A username and password are supplied, separated by a :
. It must be prefaced by the string Basic
and a space. The username:password
string is base64 encoded.
When using this authentication method in FusionAuth for an API, the username must be the string apikey
in lowercase. The password may be any API key with the appropriate permission for the endpoint being called.
Basic authentication using API key is only utilized by a select few FusionAuth APIs. These are typically integrated with other software packages which expect to authenticate using basic auth.
Client Credentials
When an API is marked with a cogs icon such as , it means you are required to provide a JSON Web Token (JWT) with the client_credentials
grant type, with clients being represented by FusionAuth Entities.
-
An example client credentials grant using Entities.
Authorization Header Examples
The following example demonstrates the HTTP Basic Authorization header.
Authorization: Basic YXBpa2V5OjY5Y1dxVW8wNGhpNFdMdUdBT2IzMmRXZXQwalpkVzBtSkNjOU9yLUxEamNIUXFMSzJnR29mS3plZg==
The following is a curl example using the HTTP Basic Authorization header with a line break and spaces for readability.
curl -X GET \
-H 'Authorization: Basic YXBpa2V5OjY5Y1dxVW8wNGhpNFdMdUdBT2IzMmRXZXQwalpkVzBtSkNjOU9yLUxEamNIUXFMSzJnR29mS3plZg==' \
'https://local.fusionauth.io/api/prometheus/metrics'
JWT Authentication
When an API is marked with a blue identity icon such as it means you may call this API without
an API key. Instead, provide a JSON Web Token (JWT). A JWT is obtained from the Login API or an OAuth grant. The token will also be provided as an HTTP Only Session cookie. If cookies are being managed for you by the browser or some
other RESTful client, the JWT cookie will automatically be sent to FusionAuth on your behalf. In this case, you may omit the Authorization
header.
Authorization Header Examples
The following example demonstrates the HTTP Authorization header using the Bearer
schema. Prior to version 1.12.0
only the JWT
schema was available.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo
The following is a curl example using the HTTP Authorization header using the Bearer schema with a line break and spaces for readability. Prior to version 1.12.0
only the JWT schema was available.
curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo' \
https://example.fusionauth.io/api/user
Cookie Example
If a cookie is provided on a request to an endpoint which accepts an API key or an JWT, the API key will be preferred.
The following is an HTTP GET request with the JWT Access Token provided as a cookie.
GET /api/user HTTP/1.1
Cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo
No Authentication Required
When an API that is marked with a green unlocked icon such as it means that you are not required to provide an Authorization
header as part of the request. The API is either designed to be publicly accessible or the request may take a parameter that is in itself secure.
Managing API Keys
Navigate to
to manage API keys.Create as many API keys as you like, each one may be optionally limited in ability to minimize security risk.
For example, the User API /api/user
has five HTTP methods, GET
, POST
, PUT
, PATCH
and DELETE
. While each API may have different semantics, in a general sense you can think of these HTTP methods as being retrieve, create, update, partial update, and delete respectively. With that in mind, if you’d like to create an API key that can only retrieve users, limit the API key to the GET
method on the /api/user
API.
When you create an API key, the key value is defaulted to a secure random value. However, the API key is simply a string, so you may set the key value to super-secret-key
if you’d like. A long and random value makes a good API key in that it is unique and difficult to guess, so allowing FusionAuth to create the key value is recommended.
Managing API Keys via the API
Prior to version 1.26.0, the FusionAuth administrative user interface was the only way to create API keys. This functionality was not available through an API. Starting from version 1.26.0, API keys may be created using an API. Please refer to the API Key API for more information.
Create an API Key

Form Fields
- Id
-
The unique Id of this API key.
- Key
-
The unique string representing the API key. This is what is presented in the
Authorization
header for requests to FusionAuth. - Description
-
An optional description of this API key.
- Tenant
-
The optional tenant to which this API key will be assigned. This value cannot be changed once the API key is created.
When you assign an API key to a tenant, any requests made with this key will only be able to operate on users, applications, groups, and other entities in the selected tenant.
- Endpoints
-
One or more endpoints this API key will be authorized to access.
Selecting no endpoints will authorize this key for all API endpoints.
- Key Manager
-
Enable to have this key be a key manager. When a key is a key manager, it can be used to call the API keys APIs.
Being able to create other API keys via the API is a privileged operation. Use it wisely.
Any attempt to call the API Keys API with a non-manager key (
keyManager
set tofalse
) will return a HTTP response status code401
.
Making an API Request Using a Tenant Id
Some resources in FusionAuth are scoped to Tenants such as Users, Groups and Applications. When more than one tenant exists, APIs managing these entities may require a Tenant Id to ensure the request is not ambiguous.
For example, once more than one tenant exists, you may no longer retrieve a user by email address without specifying the Tenant Id because a user’s email address is not unique across all tenants.
In many cases FusionAuth can detect the intended Tenant Id by inferring this value from other unique identifiers. For example, if you update a User by the unique User Id, the Tenant Id is not required. The User Id is unique across all tenants and FusionAuth can resolve the Tenant Id on your behalf.
When a request may be ambiguous without the Tenant Id, such as the email address search described above, or if you want to scope a request to a single tenant for security purposes, there are two supported methods to provide the tenant Id to FusionAuth during the API request. The first is by using an HTTP header, and the other is using an API key that has been assigned to a specific tenant.
Using an HTTP Header
The following example demonstrates an API request to an API endpoint requiring tenantId
, using the X-FusionAuth-TenantId
HTTP header and a bearer token scoped to all tenants.
curl -v -X POST \
-H 'Authorization: bf69486b-4733-4470-a592-f1bfce7af580' \
-H 'X-FusionAuth-TenantId: 6c9e9669-9670-4f85-9f16-8396c2206f7f' \
-H 'Content-Type: application/json' \
-d '{"group": {"name": "Admin"}}' \
"http://localhost:9011/api/group"
Using an API key
You may optionally create an API key scoped to a particular tenant.
Tenant scoped keys can retrieve configuration for FusionAuth entities such as identity providers and lambdas that may be shared between tenants.
Make sure you lock down the needed endpoints permissions as well as specifying the tenant.
Below, we have selected the Pied Piper
tenant for this API key. Only Users, Groups and Applications belonging to the Pied Piper
tenant will be visible to this API.

The following example demonstrates an API request to an API endpoint requiring tenantId
, using the tenant-scoped API key.
curl -X POST \
-H 'Authorization: oa06-d9uxCHTorBOkVdh_QzsX_iEEYARGv8udnMMLJ8' \
-H 'Content-Type: application/json' \
-d '{"group": {"name": "Admin"}}' \
"http://localhost:9011/api/group"
Tenant Errors
If you make an API request when the Tenant Id is required, you will receive a 400
response code with the following response body.
{
"generalErrors" : [ {
"code" : "[TenantIdRequired]",
"message" : "A Tenant Id is required to complete this request. To complete this request, you may assign a Tenant to your API key, or add the X-FusionAuth-TenantId HTTP request header with the Tenant Id."
} ]
}
You could make a request to retrieve a User or Application by Id but provide the incorrect Tenant Id. If the Tenant Id provided does not correspond to the Tenant in which the User or Application exists, the API will return an error indicating the object could not be found, either by returning a 404
status code, or some sort of validation error.