Setting up API Policies
How to set up authentication and logging policy for your API.
To have external access to your API, and to define the authentication methods for controlling who can use it, API Policies are required.
In addition, API Policies are used to set up API Monitoring and logging for your API.
Step by Step Tutorial Available
If you prefer more visual or interactive guidance on how to add an API Policy to your API in Frends, you can find a step-by-step walkthrough from your own environment's home page, under Onboarding by selecting "Tutorial 5, Step 3: API authentication with Policies" tutorial.
API Policy Creation
In an API policy, you define the name for the policy and what API endpoints and HTTP methods it is targeting.
It can either target few specific endpoints and methods, or include an implicit wildcard to match whole API and not specific endpoints or methods for them.
Each policy can also target multiple APIs, and also endpoints not included in any API, if there are other resources under Frends environment's url you would like the policy to consider. This can be useful for setting up general logging policy to log all connections coming to your Frends Agent.
Throttling can also be set for each endpoint separately, as well as for the authentication methods, depending on your requirements.
API Authentication
To set up authentication into the policy, you can create a New identity to the policy. Options here are OAuth, private application and API key.
OAuth here refers to external OAuth application authentication, which can be connected to Frends through Administration > OAuth applications menu.
Private application refers to OAuth authentication where the issuer is not defined, or is the Frends tenant itself. These can be configured under Administration > Private applications menu.
API key can be configured under Administration > API keys menu, which are then enabled to be used in the specified API endpoints here.
Instead of specified authentication method, you can also enable public access, which would enable anyone to access the specified endpoints without authentication. Enabling public access will replace all other authentication methods.
Regardless of the authentication method chosen, a target Agent Group has to be defined. It can be one or more Agent Groups, and it specifies which Agent Groups the current Policy and authentication rules apply to. For API key authentication, the target Agent Group is defined with the API key and not in this view.
If Public Access is enabled, you will need to create another Policy if you would like to have authentication enabled for other Agent Groups than what is defined for Public Access.
For other authentication methods, you can specify multiple for the single Policy to allow different authentication methods for your API at the same time. Different authentication methods can also target different Agent Groups.
Logging Configuration
Finally, you can add a logging configuration to the API policy, to define whether or not API events should be logged for the targeted endpoints in specified Agent Groups, and what details are logged.
These can be useful to set up separately for development, testing and production uses, both to enable better debugging capabilities but also to then reduce logged data amounts from production use as well as for privacy and security reasons.
Combining Policies
A single policy does not need to do everything. A common pattern is a broad logging-only policy covering / to capture all traffic, combined with more targeted authentication policies. Different policies can also apply different rules per Agent Group.
The same method and path combination can only be covered by one policy per Agent Group. Frends validates this at save time and flags any overlap. If you need multiple authentication methods on the same endpoint within the same Agent Group, add them as separate identities within a single policy.
Multiple Authentication Methods
When a policy has more than one identity type, Frends evaluates requests in a fixed order: OAuth first, then API Key, then Public Access. Only identity types actually configured in the policy participate in this chain.
OAuth evaluation is final — a token with failing claims rejects the request even if a valid API key is also present. Only an unparseable token is skipped and evaluation continues to the next method. If a policy has no OAuth identity but a request carries a parseable token, the request may still be rejected with 403 Forbidden rather than falling through to API key evaluation. Public access is always the last fallback.
You can learn more about different options and settings for API Policies in their Reference documentation page.
Last updated
Was this helpful?