API Authentication

1. Overview

The FusionAuth APIs are primarily secured using API keys, a few APIs may optionally take a JWT. Below you will find a detailed explanation of each type of authentication used in the API documentation.

•    API Key Authentication

•    JWT Authentication

•    No Authentication Required

API keys must be created in the FusionAuth admin user interface, this function is not available through an API for security reasons. To manage API keys navigate to Settings API Keys.

• Manage API Keys

• Making an API request using a Tenant Id

2. API Key Authentication

When an API is marked with a red locked icon such as    it means you are required to provide authentication. FusionAuth primarily controls access to the API through the use of an API key. All secured APIs by default all APIs will return an 401 Unauthorized response.

To enable access to a secured API create one or more API keys in the FusionAuth user interface. The API key is then supplied in the HTTP request using the Authorization header. See API Keys for more information on adding additional keys.

Authorization: 2524a832-c1c6-4894-9125-41a9ea84e013

curl -H 'Authorization: 2524a832-c1c6-4894-9125-41a9ea84e013'
     https://example.fusionauth.io/api/user?email=user@example.com

3. JWT Authentication

When an API is marked with a green identity icon such as   it means you may call this API without an API key but instead provide a JSON Web Token (JWT) pronounced "jot". These APIs may be called with a signed token in place of an API key. A JWT is obtained from the Login API. 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 send to FusionAuth on your behalf and you may omit the Authorization header.

Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo

curl -H 'Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo' \
     https://example.fusionauth.io/api/user

GET /api/user HTTP/1.1
Cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo

4. No Authentication Required

When an API that is marked with an 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 itself secure.

5. Manage API Keys

Navigate to Settings API Keys 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 four HTTP methods, GET, POST, PUT and DELETE. While each API may have different semantics, in a general sense you can think of these four HTTP methods as being retrieve, create, update and delete respectively. With that in mind, if you’d like to create an API key that can only retrieve users, you would limit the API key to the GET method on the /api/user API.

When you create an API key the key is defaulted to a secure random value but the API key is simply a string, so you may call it super-secret-key if you’d like. However a long and random value makes a good API key in that it is unique and difficult to guess.

5.1. Create an API Key

Table 1. Form Fields

Key	A unique key to be utilized to authorize API requests using the Authorization header.
Description	An optional description of how this API key will be utilized.
Tenant	The optional tenant to which this API key will be assigned. This value cannot be changed once the API key is created. This field is only displayed when more than one tenant exists. When you assign an API key to a tenant, you will only be able to operate on users, applications, and groups in the selected tenant.
Endpoints	Select one or more endpoints this API key will be authorized to access. Selecting no endpoints will authorize this key to all API endpoints.

6. 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 these APIs will 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 an 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 unique Id the Tenant Id is not required because 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 described above with the email address, or if you want to scope a request to single tenant for security purposes you will need to use one of the following methods to add the Tenant Id to the request.

In order to make API requests to FusionAuth for a particular Tenant you will need to provide the tenantId.

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.

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"

6.2. Using an API key

You may optionally create an API key that is scoped to a particular tenant. To create an API key navigate to Settings API Keys.

Similar to the example screenshot above where we created a new API key, in this example 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.

HTTP Authorization Header example

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"

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