Preparing your Frends API for publishing

APIs published in API Portal require authentication to be set up separately.

Before your API can be consumed through the API Portal, you need to set up the proper authentication and authorization in your Frends Tenant for the published APIs. The API Portal automatically manages authentication by creating Private Applications and tokens for each organization in API Portal, but you need to configure API Policies in Frends to accept and validate these tokens.

Understanding API Portal Authentication

When an organization requests access to an API Product in the API Portal, the portal automatically creates a Private Application in your Frends Tenant for that organization. Each organization is mapped to a single Private Application, ensuring consistent identity management across all their API subscriptions.

When access to an API Product is granted, API Portal generates an authentication token for that organization. This token contains a claim called apiproductid that identifies which API Product the token is valid for. Each API Product the organization has access to receives its own token with a matching API Product ID claim.

This architecture means you don't need to manually create Private Applications or generate tokens for API Portal users—the portal handles all of this automatically. However, you do need to configure your APIs and specifically API Policies to recognize and accept these tokens based on their API Product ID claim.

Requirements

To configure API Policies for API Portal integration, you need at least the Editor role in Frends, or a custom role with the ApiPolicy.Edit permission. This allows you to create and modify API Policies that control access to your APIs.

Creating an API Policy for APIs in API Products

Navigate to APIs > API Policies in your Frends Tenant to create a new API Policy. If you already have existing policies for your APIs, you can modify them to work with API Portal, or create a separate policy specifically for API Portal traffic.

Start by giving your policy a descriptive name that indicates it's for API Portal use. In the policy configuration, specify which API operations this policy should apply to. You can target specific APIs and operations, or use wildcards to match entire APIs. Make sure to include all the operations that are part of your API products in the portal.

In the policy settings, ensure that Public access is disabled. API Portal uses Private Application authentication, so public access would bypass the authentication mechanism entirely.

Setting Up the Private Application Identity

Click on New identity to add a Private Application authentication method to your policy. You'll be prompted to provide a name for this identity—this is not the name of a specific Private Application, but rather a label for this authentication rule within your policy. Choose a descriptive name like "API Portal Access" to clearly indicate its purpose.

Select the targeted Agent Groups where this authentication should apply. For example, if your API Portal products run in your Production Agent Group, select that Agent Group here. You can target multiple Agent Groups if your API Products run in different Environments.

Configuring Token Rules

With the identity created, you now need to define the rules that determine which tokens are allowed to access your APIs. This is where you specify that tokens must contain the apiproductid claim.

Create a new rule for the apiproductid claim. The most flexible approach is to create a rule that allows tokens containing any API product ID, rather than specifying individual product IDs. This way, as you create new API products in the portal, they will automatically work with this policy without requiring updates.

To allow all tokens with an API product ID regardless of which specific product, you can use a rule that checks whether the apiproductid claim exists in the token. Alternatively, if you want more granular control, you can create rules that match specific API product IDs using the Exact, Contains, or Regex matching options.

By default, Frends will validate that the token hasn't expired and that the issuer and audience claims match your Frends Tenant. This ensures that only tokens generated by your Tenant's API Portal are accepted, providing security against tokens from other sources.

If you need to add additional restrictions, you can create more rules based on other claims in the tokens. For example, you might want to restrict access based on organization properties or other custom claims that the API Portal includes in its tokens.

Saving and Testing Your Policy

Once you've configured all the necessary rules, click Save Changes to save your API Policy. The policy will immediately take effect on the specified Agent Groups, and tokens generated by the API Portal will be able to authenticate to your APIs.

To verify that your policy is working correctly, you can test it using a token from the API Portal. Organizations that have been granted access to your API Products will have tokens available in their organization settings. Copy one of these tokens and make a test request to your API using the token in the Authorization header. If the policy is configured correctly, the request should succeed.

Managing Multiple API Products

If you're publishing multiple API products through the API Portal, you don't need to create separate API Policies for each one, as long as they all share the same authentication requirements. A single API Policy with an apiproductid claim rule will handle authentication for all your API products.

However, if you have different security requirements for different API products—such as different Agent Groups, throttling rules, or logging configurations—you can create multiple API Policies, each targeting the specific operations included in those products and configured with the appropriate rules.

Additional Considerations

Remember that the API Portal generates Private Applications and tokens automatically using the Frends Platform API. These automated operations only create new Private Applications and tokens—they won't modify or delete existing ones. This ensures that your manual authentication configurations remain safe even when API Portal is managing its own authentication resources.

If you need to revoke access for an organization, you can do so through the API Portal's organization management interface. This will revoke or delete the associated tokens, preventing further access to your APIs. You can also manually manage these Private Applications and tokens in your Frends tenant's Administration section if needed.

For more detailed information about Private Applications and API Policies in Frends, see the How to use Private Applications for authenticating to Frends API and Setting up API Policies guides.