API introduction
Welcome to the Frontegg API documentation. This guide is your starting point before making your first API request Please read this carefully to avoid common issues and ensure a smooth development experience.
API Categories
Frontegg APIs are grouped into three categories. Understanding the difference between them is essential.
Authentication APIs
The Authentication endpoints enable:
- Secure user login
- Multi-factor authentication (MFA)
- Passwordless authentication
- Social login integrations
Management APIs
Management endpoints are used to:
- Configure SSO (SAML, OIDC)
- Manage user roles, permissions and configurations
Self-Service APIs
The Self-Service endpoints allow end-users to:
- Create, update, or delete SSO configurations
- Update account settings
API access
Management APIs require environment-level authorization, can only be used with your environment token, and are responsible for configuring various environment settings. These requests should be directed to api.frontegg.com
.
Authentication and Self-Service APIs can be accessed using either the environment token or an authenticated user's token. To call these APIs, you need the Client ID and API Key obtained from your Frontegg portal. These types of requests use the api.frontegg.com
prefix.
When sending requests in a tenant context, they should be directed to your specific subdomain on frontegg.com
, or to a custom domain if one has been 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:
Self-service (User)
--location -g --request GET 'https://[your-subdomain].frontegg.com/identity/resources/users/v3/me'
--header 'Authorization: Bearer {{user-JWT}}'
--data-raw ''
When and where to use headers
Routes that are marked as Self-Service can be called in two different ways, depending on the type of token you're using.
If you're using an environment token, you must include the frontegg-user-id
and/or frontegg-tenant-id
headers, depending on the specific API requirements. These calls should be directed to:
https://api.{{region}}.frontegg.com/xxxx
Alternatively, Self-Service routes can also be called using a user token, such as one generated via the Authenticate user with password endpoint. In this case, you should send the request to your Frontegg subdomain or custom domain:
https://[your-frontegg-or-custom-domain]/xxxxxx
When using a user token, you do not need to include any headers — the user and tenant information will be automatically extracted from the JWT.
API Gateway by Region
Region | Gateway |
---|---|
EU | https://api.frontegg.com |
US | https://api.us.frontegg.com |
AU | https://api.au.frontegg.com |
CA | https://api.ca.frontegg.com |
Performing Your First API Call
Before calling any of Frontegg's APIs, you'll need to authenticate your environment using Bearer authorization tokens. To obtain it:
- Go to your Frontegg Portal → [Environment] → Keys & Domains.
- Copy your Client ID and API Key.
- Make a POST request to the environment authentication endpoint with these values:
curl -X POST https://api.frontegg.com/auth/vendor
-H 'Content-Type: application/json'
-d '{
"clientId": "YOUR_CLIENT_ID",
"secret": "YOUR_API_KEY"
}'
You'll receive a bearer token in the response. Use this token in the Authorization
header for subsequent Management API or Self-Service API calls.
Generating and using a TypeScript SDK
You can generate a fully-typed TypeScript (or JavaScript) SDK from Frontegg's OpenAPI specification using the api
library. This tool simplifies API consumption by generating a client library with built-in TypeScript types and convenient method access.
Install the SDK
npx api install https://github.com/frontegg/openapi-public/blob/master/apis-combined.json
Troubleshooting common errors
Errors such as { "errors": ["Failed to verify vendor JWT"] }
are typically caused by misusing API contexts or directing requests to the wrong gateway. These issues often arise when Management APIs are mistakenly called in a Self-Service context, or vice versa, or when the endpoint does not match your account's deployment region.
To verify your Environment token, use the Environment authentication API. Make sure to include your Client ID
and API Key
, which you can find in the Frontegg Portal under [ENVIRONMENT] → Keys & Domains.
Pay close attention to the URL you're using for API calls. Management APIs must be called through api.frontegg.com
, while Self-Service or tenant-scoped APIs should go through your specific subdomain—typically in the format app-<your-tenant-id>.frontegg.com
— or through your configured custom domain. Using the wrong domain for a given API context will result in authorization failures.