Explore Frontegg's API, make your first API call and avoid common errors
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:
Vendors, Tenants, and Users
When you first explore our API reference, you'll find APIs specific tagged as Vendor or Self-service APIs. The difference lies in whether you're making the specific call as a Vendor, or if your Tenant accounts perform them— hence the 'self-service' tag.
The key personas in Frontegg are its Vendors, Tenants, and Users. Vendors are Frontegg's direct customers. As a vendor, you can customize and implement sophisticated security measures and authentication protocols for your customers (Tenants), and across multiple environments —development, staging, QA, and production. Vendors have control over advanced configurations and determine what their tenants can or cannot see upon logging in as well as what they can configure in their account or for their sub-tenants. Your Tenants can manage their workspaces via their Admin Portal platform, using features that you enabled for their usage. Users are your end-customers and (i.e., the users of your your tenants and their sub-tenants). Users can be allocated roles and permissions, be divided into groups, etc.
Lean more about the key personas in Frontegg in the User Management Architecture topic.
Performing Your First API Call
Common errors
Check the last section in this topic Solving Common Errors to familiarize yourself with the nuances required in order to prevent them.
Frontegg's APIs are based on Bearer Authorization tokens.
To authenticate your environment and get a vendor JWT 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 vendor authentication endpoint
Both Client ID and API Key are available via the [Env Settings menu] under each environments 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 as a vendor, you need to use the Client ID and API Key you fetched from your 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. 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 (Tenant) :
\--location -g --request GET 'https\://[your-subdomain].frontegg.com/identity/resources/users/v3/me'
--header 'Authorization: Bearer {{user-JWT}}'
--data-raw ''
Environment (Management) :
--location -g --request GET '<https://api.frontegg.com/identity/resources/users/v3/me'>
--header 'frontegg-user-id: xxxxxxx'
--header 'frontegg-tenant-id: xxxxxxx'
--header 'Authorization: Bearer {{vendor-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 vendor or tenant context or calling the wrong gateway based on your account's location. Here's how to fix them:
- API Gateway: Make sure you're using the correct API gateway for your Frontegg account's location:
- EU accounts: api.frontegg.com
- US accounts: api.us.frontegg.com
- AU accounts: api.au.frontegg.com
- Vendor Token: To ensure your vendor token is correct, use the Vendor authentication API endpoint. Pass your Client ID and API Key from the Frontegg Portal ➜ [ENVIRONMENT] ➜ Env Settings page.
- API URL Context: Be careful not to mix up API calls in vendor/tenant context. Make sure you're not calling app-xxx.frontegg.com (tenant context) when you should be calling api.frontegg.com (vendor context).