FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Release Notes
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Entity Management
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Key Master
    • SCIM
    • Search
    • Authentication and Authorization
    • Integration Points
    • Localization and Internationalization
    • Editions and Features
    • Roadmap
  • 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
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Admin Guide
    • Overview
    • Config Management
    • Licensing
    • Monitoring
    • Proxy Setup
    • Securing
    • Technical Support
    • Troubleshooting
    • Upgrading
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Tutorial
  • APIs
    • Overview
    • Authentication
    • Errors
    • 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
      • Kafka
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM EnterpriseUser
      • SCIM Group
      • SCIM Service Provider Config.
      • SCIM User
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • OpenAPI
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Examples
    • Helpers
    • Localization
    • Template Variables
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
    • Email Variables
    • Message Templates
  • 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
      • 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 Duplicate Create
      • User Login Id Duplicate 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 Registration Create
      • User Registration Create Complete
      • User Registration Delete
      • User Registration Delete Complete
      • User Registration Update
      • User Registration Update Complete
      • User Registration Verified
      • User Two Factor Method Add
      • User Two Factor Method Remove
      • User Update
      • User Update Complete
  • Example Apps
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • 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. Converter
    • SCIM User Req. Converter
    • SCIM User Resp. Converter
    • Sony PSN Reconcile
    • Steam Reconcile
    • Twitch Reconcile
    • Twitter Reconcile
    • Xbox Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Epic Games
    • External JWT
      • Overview
      • Example
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Nintendo
    • OpenID Connect
      • Overview
      • Azure AD
      • Discord
      • Github
    • Sony PlayStation Network
    • Steam
    • Twitch
    • Twitter
    • SAML v2
      • Overview
      • ADFS
    • SAML v2 IdP Initiated
      • Overview
      • Okta
    • Xbox
  • Messengers
    • Overview
    • Generic Messenger
    • Kafka Messenger
    • Twilio Messenger
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Self Service Account Mgmt
    • Overview
    • Updating User Data & Password
    • Add Two-Factor Authenticator
    • Add Two-Factor Email
    • Add Two-Factor SMS
    • Customizing
    • Troubleshooting
  • Advanced Threat Detection
    • Overview
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Plugins
    • Writing a Plugin
    • Custom Password Hashing
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Multi-Factor Authentication
    • Multi-Tenant
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • User Control & Gating
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
    • Setup Wizard & First Login
    • Register/Login a User
    • Start and Stop FusionAuth
    • Authentication Tokens
    • Key Rotation
    • JSON Web Tokens
    • Prometheus Setup
    • Switch Search Engines
    • Two Factor (pre 1.26)
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Hashes

    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

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

    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

    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.

    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.

    Create a Tenant API Key

    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.

    Tenant Required Error
    {
      "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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    © 2021 FusionAuth
    Subscribe for developer updates