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:

•  API Key Authentication

•  Basic Authentication using an API Key

•  Client Credentials

•  JWT Authentication

•  No Authentication Required

You can also learn about:

• Managing API Keys

• Making an API Request Using a Tenant Id

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

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: Basic YXBpa2V5OjY5Y1dxVW8wNGhpNFdMdUdBT2IzMmRXZXQwalpkVzBtSkNjOU9yLUxEamNIUXFMSzJnR29mS3plZg==

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: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo

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

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

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 to false) will return a HTTP response status code 401.

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.

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"

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