API introduction

Welcome to Frontegg's APIs! This is your first stop before performing your first API request. Please read thoroughly to familiarize yourself with the nuances and to ensure easy navigation and performance. Before diving in, let's clear out some terms first:

Different types of endpoints

Authentication endpoints: Enable secure user login, multi-factor authentication (MFA), passwordless options, and social login integrations, allowing for a flexible and robust sign-in experience.

Management endpoints: Require environment-level authorization and provide full control over SSO (SAML and OpenID Connect) resources, user roles, permissions, and configurations. These endpoints are designed for administrative use, allowing for centralized identity and access management.

Self-Service endpoints: Accessible with a user token (JWT), these endpoints empower users to manage their SSO connections and other account settings. Users with the necessary permissions can create, update, or delete SSO configurations directly, ensuring they have the tools to manage their access securely and independently.

API Gateway: Make sure you're using the correct API gateway for your Frontegg account's region:

• EU accounts: api.frontegg.com
• US accounts: api.us.frontegg.com
• AU accounts: api.au.frontegg.com
• CA accounts: api.ca.frontegg.com

Using as an SDK

api is a library that facilitates creating an SDK from an OpenAPI definition. You can use it for creating an SDK for TypeScript or JS (+ TypeScript types).

npx api install https://github.com/frontegg/openapi-public/blob/master/apis-combined.json

Performing your first API call

Frontegg's APIs are based on Bearer Authorization tokens.
To authenticate your environment and get an environment token to use in further API requests, you'll need to pass your environment's Client ID and API key as the clientId and secret respectively to the environment authentication endpoint

Both Client ID and API Key are available via the Keys & domains under each environment in the Frontegg portal.

Management, authentication, and self-service APIs

You'll notice that some APIs are marked as Management APIs. Those can be used with your environment token only and are responsible for various environment settings. They should be directed to api.frontegg.com.
APIs tagged as Authentication or Self-service can be accessed using both the environment token and an authenticated user's token. To call these APIs, you need to use the Client ID and API Key you fetched from your Frontegg portal. These type of calls begin with an api.frontegg.com prefix.

When sending requests in a tenant context, it should be directed to your specific subdomain on frontegg.com or a custom domain if such was configured. For example,
**app-**frtqiefxjqn9.frontegg.com**/identity/resources/users/v3**.

The following example is that of a GET Users request, that can be used with both types of Bearer tokens. Note the nuances:

--location -g --request GET 'https://[your-subdomain].frontegg.com/identity/resources/users/v3/me'  
--header 'Authorization: Bearer {{user-JWT}}'  
--data-raw ''

Solving common errors

Common errors e.g., {"errors":["Failed to verify vendor JWT"] typically occur as a result of a mix-up in performing calls in either management or self-service context or calling the wrong gateway based on your account's location. Here's how to fix them:

Environment token: To ensure your Environment token is correct, use the Environment authentication API endpoint. Pass your Client ID and API Key from the Frontegg Portal → [ENVIRONMENT] → Keys & domains page. API URL Context: Be careful not to mix up API calls in management/self-service context. Make sure you're not calling app-xxx.frontegg.com (self-service context) when you should be calling api.frontegg.com (management context).