Frontegg powers your application with the ability to authenticate from different other sources (such as CLI tools, Machines, and any other non-browser related activities)

For that, you can leverage the Frontegg API tokens management to allow:

• Your customers to login via CLI tools and backend activities
• Your customers to manage the API tokens via the Admin Portal

Types of API tokens

Frontegg supports 2 types of API tokens:

• User (personal) tokens
• Tenant tokens

📘

Getting started with API tokens

Getting started with API tokens is easy. Just make sure you enable them via the Self service module on the Frontegg management portal

User (personal) tokens

User tokens are tied to the user and will always contain the user context and the roles/permissions of the user on the active tenant.

The user token will be deleted once the user is deleted from the system.

Creating personal tokens

Creating personal tokens is possible using 2 methods:

• Via the admin portal (for the end-user)
• Via API call

Creating personal tokens via the Admin Portal

After embedding the Admin Portal, allow your users to generate tokens for themselves by following this guide

Creating personal tokens via API

Want to experiment API tokens before allowing your users with the self-service experience they deserve? No worries - we got you covered!

Generating API token via API is easy as 1,2,3:

Authenticate your workspace

curl --location --request POST 'https://api.frontegg.com/auth/vendor' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[your-workspace-client-id]",
    "secret": "[your-workspace-secret]"
}'

Create user token

Using the access token from the /auth/vendor create the user API token. You will need to pass:

• frontegg-user-id header - To represent the user ID which the token will be created for
• frontegg-tenant-id header - To represent the tenant ID which for the context of the user
• description - to represent logical description which will help you and the user remember what this token is for

curl --location --request POST 'https://api.frontegg.com/identity/resources/users/api-tokens/v1' \
--header 'frontegg-user-id: acme-user-id' \
--header 'frontegg-tenant-id: acme-id' \
--header 'Authorization: Bearer [token-from-vendor-authentication]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "Token for CLI calls"
}'

This API will return clientId and secret which will be used for the actual JWT exchange.

📘

Shhhhh... It's a secret...

Secrets are shown clear only once on the API tokens creation. You know why? Because they are saved hashed and bcrypted and CANNOT be reversed.

You are good to go to Authenticate your API!

Tenant tokens

Tenant tokens are tied to the tenant and don't have any notion of user on them. The roles/permissions on the API tokens match the scopes that were given to the token when it was created.

The tenant token will be deleted once the user is deleted from the system.

Creating tenant tokens

Creating tenant tokens is possible using 2 methods:

• Via the admin portal (for the tenant administrator)
• Via API call

Creating tenant tokens via the Admin Portal

After embedding the Admin Portal, allow your tenant administrators to generate tokens for themselves by following this guide

Creating tenant tokens via API

Want to experiment API tokens before allowing your users with the self-service experience they deserve? No worries - we got you covered!

Generating API token via API is easy as 1,2,3:

Authenticate your workspace

curl --location --request POST 'https://api.frontegg.com/auth/vendor' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[your-workspace-client-id]",
    "secret": "[your-workspace-secret]"
}'

Create tenant token

Using the access token from the /auth/vendor create the user API token. You will need to pass:

• frontegg-tenant-id header - To represent the tenant ID which the token is created for
• description - to represent logical description which will help you and the user remember what this token is for
• roleIds - ids to represent the roles which the token will be created for
• metadata (optional) - JSON which can include additional metadata for the token

curl --location --request POST 'https://api.stg.frontegg.com/identity/resources/tenants/api-tokens/v1' \
--header 'frontegg-tenant-id: acme-id' \
--header 'Authorization: Bearer [token-from-vendor-authentication]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "Acme CLI tool",
    "roleIds": ["role-uuid-1", "role-uuid-2"],
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}'

This API will return clientId and secret which will be used for the actual JWT exchange.

📘

Shhhhh... It's a secret...

Secrets are shown clear only once on the API tokens creation. You know why? Because they are saved hashed and bcrypted and CANNOT be reversed.

You are good to go to Authenticate your API!

Authenticate your API token

Using the clientId and secret from the token creation step, you can now exchange your token to a perfectly signed JWT.

curl --location --request POST 'https://[your-frontegg-workspace-url]/identity/resources/auth/v1/api-token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "[the-api-token-client-id]",
    "secret": "[the-api-token-secret]"
}'