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

• API Key Permissions

• Client Side API Keys

• Troubleshooting

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

Authorization: 7DUrRlA75b5LBRARYoTmScCTk6G6U1nG8R9mr7MGnvzA7AMxEXAMPLE

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: 7DUrRlA75b5LBRARYoTmScCTk6G6U1nG8R9mr7MGnvzA7AMxEXAMPLE' \
     '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 an API key is only utilized by a select few FusionAuth APIs. These are typically integrated with other software packages which expect such an authentication method.

Authorization: Basic YXBpa2V5OjY5Y1dxVW8wNGhpNFdMdUdBT2IzMmRXZXQwalpkVzBtSkNjOU9yLUxEamNIUXFMSzJnR29mS3plZg==

curl -X GET  \
-H 'Authorization: Basic YXBpa2V5OjY5Y1dxVW8wNGhpNFdMdUdBT2IzMmRXZXQwalpkVzBtSkNjOU9yLUxEamNIUXFMSzJnR29mS3plZg==' \
'https://local.fusionauth.io/api/prometheus/metrics'

Client Credentials

When an API is marked with a red passport icon such as   , the authorization becomes a two step process. To complete the process and generate a token you must:

• Use the client_credentials grant to obtain a JSON Web Token (JWT). The requester should be granted the appropriate permissions on the target entity.

• Make a request of the API with the JWT in the Authorization header using the Bearer scheme.

If the JWT is expired or incorrect, the request will fail.

The requesting and target entities, as well as permissions, are all managed using Entities.

Client Credentials Examples

Here is an example client credentials grant using Entities.

Here’s another example. First, you get the token:

curl -u "eb6fce6a-4ed8-4010-8091-1709fc823329:_7bz1Ct1Sode-zIyevcQFSyzW9w3TkfKSWuS-Ls8vQQ" \
  https://local.fusionauth.io/oauth2/token \
  -d 'grant_type=client_credentials&scope=target-entity:a647e989-1c7e-4386-9ec6-fa4fe6908906:scim:user:read'

Here’s an example JWT that might be returned:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImd0eSI6WyJjbGllbnRfY3JlZGVudGlhbHMiXSwia2lkIjoiMDUzYWE1Y2QxIiwidXNlIjoic2NpbV9zZXJ2ZXIifQ.eyJhdWQiOiJhNjQ3ZTk4OS0xYzdlLTQzODYtOWVjNi1mYTRmZTY5MDg5MDYiLCJleHAiOjE2NTU3NjExNzAsImlhdCI6MTY1NTc1NzU3MCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiJlYjZmY2U2YS00ZWQ4LTQwMTAtODA5MS0xNzA5ZmM4MjMzMjkiLCJqdGkiOiJjMTMxYThiZi0yN2E5LTQ2MGUtOTFiYi0xOTI5NmE2MDFlMTEiLCJzY29wZSI6InRhcmdldC1lbnRpdHk6YTY0N2U5ODktMWM3ZS00Mzg2LTllYzYtZmE0ZmU2OTA4OTA2OnNjaW06dXNlcjpyZWFkIiwidGlkIjoiNTc5NzA5ZjQtMWYyMi1jMTMxLWRlMjYtZTc3MGUwNGJhMTJkIiwicGVybWlzc2lvbnMiOnsiYTY0N2U5ODktMWM3ZS00Mzg2LTllYzYtZmE0ZmU2OTA4OTA2IjpbInNjaW06dXNlcjpyZWFkIl19fQ.XNLUF-8IT5Mh411uD0jOb_3aaT5YJrbM6q4PZrOxfbQ

After retrieving the JWT, place it in the Authorization header with a prefix of `Bearer `. Then you call the API endpoint:

curl -XGET -H "Authorization: Bearer eyJhbG..." 'https://local.fusionauth.io/api/scim/resource/v2/Users'

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 a string, so you may set it to super-secret-key, a UUID such as 02e56c92-f5e1-4b0f-8298-b5103bc7add7, or any other string value that you’d like. A long and random value makes a good API key because 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."
  } ]
}

API Key Permissions

Each API Key can be granted zero or more endpoint permissions. Each permission corresponds to an endpoint and an HTTP method. API keys are limited to the allowed endpoints and HTTP methods.

These permissions are managed via the API Key API or in the administrative user interface under the Endpoints section. When using the administrative user interface, you may click on the HTTP method column or the endpoint row. Either will toggle all the settings for the column or row, respectively.

For example, if you were to grant an API key POST permissions on /api/user, the API key would be able to create users in FusionAuth. Any calls with this API key would be denied access to any other functionality, including listing users, creating applications, and deleting registrations.

Calling other endpoints would result in a 401 response code.

Client Side API Keys

When interacting with FusionAuth from a client side application, such as a React or Angular front end, you have a few options.

If you are authenticating the user, use the standard OAuth Authorization Code grant. You can either forward the browser or webview to FusionAuth or use an iframe.

If you are using one of the APIs which does not require an API key, such as the change password API, you can interact directly with the API. These APIs tend to be more limited in functionality when no API key is presented, but may suit your needs.

If you need to use an API requiring authentication from client code, such as the registration API, you have two options:

• Use a server side component which can securely hold the API key and monitor access for abuse. This can be in any server side language or framework. The client code then sends requests to the server side component, and the server side code makes requests of FusionAuth. This is the recommended option.

• Create an API key with extremely limited permissions and distribute it. Since stealing the key when used on the client side is trivial—​all an attacker has to do is 'view source'--make sure you have carefully considered the risk and result of someone stealing and using the key outside of your application. You can also monitor FusionAuth usage with webhooks, use IP ACLs to limit where the API key can be used from, or place an HTTP proxy in front of FusionAuth to further limit access. Plan to rotate the key regularly to limit the impact.

Troubleshooting

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.