Client Libraries and SDKs

On this page

Client libraries and SDKs help you integrate your application with FusionAuth. All FusionAuth client libraries are open source and hosted on the FusionAuth GitHub account. You can fork the libraries, change them, and read the code to learn how they work.

To generate your own client or browse endpoints and schemas, see the OpenAPI specification.

SDKs Versus Client Libraries#

A client library is a thin wrapper over the FusionAuth APIs. A client library covers all public FusionAuth API endpoints. Developers assemble the pieces to extend or manipulate FusionAuth to meet their needs.

Use a client library to manage FusionAuth from code. For example, you can rotate client secrets on a schedule. You can also use a client library to build login experiences that differ from the experiences FusionAuth offers out of the box. For example, you can prompt for a username, look up the User, show a custom password field, and then ask for a favorite color.

An SDK is an opinionated set of higher level constructs that focuses on a subset of functionality. SDKs help you finish common tasks quickly. SDKs usually target front end developers who work with mobile, React, Vue, Angular, or JavaScript.

An SDK provides:

  • A button or function for logging in.
  • A button or function for logging out.
  • A button or function for registering a User.
  • A filter or other way to examine roles and limit displayed information to a role or set of roles.
  • A way to refresh a token without asking the User to re-authenticate.
  • Secure access token and refresh token storage.

SDKs need minimal customization. To get both the simplicity of an SDK and the fine-grained control of a client library, use an SDK and a client library in the same application.

Languages#

The following pages cover each SDK, client library, and the OpenAPI specification:

The FusionAuth contrib repository lists community contributed client libraries for other languages. When you need a language that the page doesn't list, check the open feature requests in the GitHub issues. Open a feature request when no request exists.

Usage Suggestions#

Choose a Use Case#

Client libraries wrap the REST API. You can use a client library for two tasks.

The main task is calling the FusionAuth APIs from code. You get auto-completion and typed objects, which helps when you script configuration, automate common tasks, or copy existing Applications and Groups. The API documentation lists the JSON structure of every request and which fields each call requires. When you need the details, read the API documentation and the library source code.

The secondary task is exchanging an authorization code for tokens in the Authorization Code grant. For this task, use an OAuth library for your language instead. For a list of libraries, see the community curated list.

Client libraries don't provide higher level functionality such as token management. To request that functionality, comment on or upvote the open issue.

When a client library doesn't fit your needs, call the REST API directly.

Requests and Responses#

Each library maps a request object to the JSON that the matching API method requires. Depending on the API call, the request object is a set of string parameters or a complex object. When you use a language without static typing, read the API documentation for the operation to learn the expected fields.

Each library returns a response object with these fields:

  • A status that matches the HTTP status code from the API. The status is -1 when no HTTP request succeeded.
  • A JSON success object when the call succeeds.
  • A JSON error object with a message when the status is 4xx or 5xx.
  • An exception object when the library sent no request or the server returned no usable response.

Use Separate Clients for API Key Scopes#

When a script calls endpoints with different API key scopes, create one client instance per scope. For example, Entities accept a tenant-scoped API key, but Entity Types and Lambdas require a global API key.

Follow these rules when your library lets you set a Tenant Id on the client instance:

  • Set the Tenant Id on the tenant-scoped client only.
  • Don't change the Tenant Id on a shared client between calls.
  • Don't send a tenant header to a global-only endpoint. The endpoint fails with a 401.

Versioning#

For more information about client library versions, see Client Library Versioning.

Update Policy#

FusionAuth releases new versions of the SDKs and client libraries to track the FusionAuth API. SDKs and client libraries may also receive bug fixes, security patches, tests, code samples, and documentation changes.

These releases may update dependencies, language engines, and operating systems, because FusionAuth follows the deprecation and sunsetting policies of the underlying technologies. When the maintainer deprecates a language, framework, or operating system, FusionAuth deprecates the SDKs and client libraries that depend on the technology. FusionAuth then updates the SDKs and client libraries to use a newer version.

For more information, see Update a Client Library.