# API Policies API Policies are the access control layer for APIs in Frends. Every API endpoint that should be reachable from outside the Agent must be covered by at least one API Policy — there is no implicit public access. A policy defines which endpoints it applies to, which authentication methods are accepted, and optionally configures request throttling and API connection logging. Policies are managed from **APIs > API Policies** in the Control Panel. To learn how to create and configure policies step by step, see the [Setting up API Policies guide](https://app.gitbook.com/s/0p415NUmUmiF4ayjI81L/api-management/setting-up-api-policies).

API Policy for setting up API key authentication.

## Policy Fields Each API Policy has a name and targets one or more API endpoints and HTTP methods. A policy can cover a single endpoint such as `GET /api/v1/crm/customers`, a whole API, or even paths outside any defined API if you want to capture all traffic reaching your Agent Group. Throttling limits can be set per endpoint and also per authentication identity within the policy. The top-level fields of a policy are as follows. `Name` is the display name for the policy. It is required and must be unique within the Tenant. `Description` is an optional free-text field for documenting the purpose of the policy. `Tags` is an optional list of labels used for filtering and organising policies in the Control Panel. ### Endpoint Targeting and Path Matching Each policy contains one or more endpoint definitions under **Targeted endpoints**. Each endpoint definition has the following fields. `Method` specifies which HTTP method the endpoint definition applies to. Setting the method to `ALL` applies the definition to any HTTP method for that path. Explicit methods such as `GET` or `POST` take priority over `ALL` when both could match the same request. `Path` specifies the URL path the policy applies to. Paths use segment-based prefix matching: the path is split into segments at each `/`, and the policy path must match the beginning of the request path segment by segment. Trailing slashes are normalised on both sides before comparison, and matching is case-insensitive. A policy path of `/api/v1/crm` matches `/api/v1/crm/customers` and `/api/v1/crm/customers/123`, but does not match `/api/v1/crmadmin`, because `crm` and `crmadmin` are different segments. Path segments can include variable placeholders using curly braces, such as `{id}`, which match any single value in that position. For example, `/api/v1/crm/customers/{id}` matches `/api/v1/crm/customers/123` and all sub-paths beneath it, such as `/api/v1/crm/customers/123/contacts`. Note that a trailing slash on a path endpoint definition can block more explicit sub-paths below it from being matched. The path `/api/v1/foo/` (with a trailing slash) may prevent `/api/v1/foo/bar` from resolving correctly to its own endpoint definition. Remove trailing slashes from path definitions to avoid this. `Throttling` sets an optional request rate limit for this specific endpoint, independently of any identity-level throttling. ## Authentication Each policy can include one or more authentication **identities**. An identity defines the authentication type and the Agent Groups it applies to. Multiple identities within a single policy allow different authentication methods to be accepted on the same endpoint within the same Agent Group.

Setting up Microsoft Entra ID as OAuth provider for your API.

The supported identity types are described below. ### API Key API keys are created in **Administration > API Keys** and are scoped to an Environment rather than a specific Agent Group. When added to a policy identity, you specify how the key should be provided in requests. Multiple API keys can be grouped under the same identity, in which case they share the throttling settings for that identity. Each API Key identity has the following fields. `Name` is the display name for the identity within the policy. `API Key Name` is the name of the request header or query parameter that carries the API key. `API Key Location` specifies how the API key is passed in the request. The possible values are `Header` and `Query`. When `Header` is selected, the caller must include the key in a request header with the name defined in the `API Key Name` field. When `Query` is selected, the key is passed as a query parameter with the name defined in the `API Key Name` field. `Throttle` sets an optional rate limit that applies to all API keys in this identity collectively. `API Keys` is the list of API key values from **Administration > API Keys** that are accepted under this identity. Multiple keys can be added and will all be validated against the same location and throttle settings. Because API keys are Environment-scoped, using separate policies for the same endpoint across multiple Agent Groups in the same Environment can cause conflicts. In such cases, a private application token is a suitable alternative. ### OAuth OAuth identities connect the policy to an OAuth application configured in **Administration > OAuth applications**. The selected OAuth application defines the trusted issuer, and the identity can optionally include claims rules that further restrict which tokens are accepted. OAuth authentication uses bearer tokens passed in the `Authorization` header of the request. Each OAuth identity has the following fields. `Name` is the display name for the identity within the policy. `Targeted Agent Groups` specifies which Agent Groups this identity applies to. One or more Agent Groups can be selected. `Issuers` selects the OAuth application from **Administration > OAuth applications** that acts as the trusted token issuer for this identity. Only tokens issued by the selected application are accepted. `Throttled by claim` sets an optional rate limit that applies to all callers authenticated through this identity. `Rules` is an optional set of rules applied to the token claims after the issuer is validated. Each rule targets a specific claim field in the token and applies one of the following operators: * `Exists` — the claim must be present in the token, regardless of its value. * `Exact`— the claim must equal the specified value exactly. * `Regex`— the claim must match the regular expression. Multiple claim rules on the same identity are evaluated as a conjunction — all rules must pass for the token to be accepted. ### Private Application Private application identities use OAuth authentication where the issuer is the Frends Tenant itself, or is otherwise not defined externally. Private applications are configured under **Administration > Private applications**. Unlike API keys, private application tokens are not scoped to a specific Environment, which makes them a good alternative when you need to apply consistent authentication across multiple Agent Groups. Each Private Application identity has the following fields. `Name` is the display name for the identity within the policy. `Target Agent Groups` specifies which Agent Groups this identity applies to. One or more Agent Groups can be selected. `Private Application` selects the private application from **Administration > Private applications** whose tokens are accepted under this identity. `Throttled by claim` sets an optional rate limit that applies to all callers authenticated through this identity. `Rules` is an optional set of rules applied to the token claims after the issuer is validated. Each rule targets a specific claim field in the token and applies one of the following operators: * `Exists` — the claim must be present in the token, regardless of its value. * `Exact`— the claim must equal the specified value exactly. * `Regex`— the claim must match the regular expression. Multiple claim rules on the same identity are evaluated as a conjunction — all rules must pass for the token to be accepted. ### Public Access Enabling public access on a policy allows unauthenticated requests to reach the targeted endpoints. When public access is enabled, it replaces all other authentication methods for that policy's scope. Starting from Frends version 6.3, a public access identity can be combined with other identities within the same policy — authenticated requests are validated normally, and unauthenticated requests are treated as public access. The public access configuration has the following field. `Target Agent Groups` specifies which Agent Groups this public access rule applies to. One or more Agent Groups can be selected. ## Logging Configuration A logging configuration added to a policy controls whether API connection events are recorded for the targeted endpoints in the specified Agent Groups, and what level of detail is captured. Without a logging configuration, no API connection logs are generated for the covered endpoints. This applies only to API connection logging in API Monitoring — Process execution logs follow the Environment log settings separately.

API logging configuration options.

Each logging configuration has the following fields. `Target Agent Groups` specifies which Agent Groups the logging configuration applies to. One or more Agent Groups can be selected. `Logging fields` is a multi-select that controls which parts of the request and response are included in each API connection log entry. The options can be enabled independently of each other. `Identity` is selected by default; all other options are opt-in. * `Identity` records the authentication identity that was matched for the request — for example, the name of the API key or OAuth identity that authenticated the caller. This is the baseline option and is selected by default. It is the primary field used to identify callers in API Monitoring. * `Query Parameters` records the full query string appended to the request URL. This is useful for understanding which filters or parameters callers are using, but should be enabled with care if query strings may carry sensitive values. The logged query string is truncated at 1000 characters. * `Request Headers` records the HTTP headers sent by the caller with the request. This is useful for debugging how clients are sending requests and what metadata they include, such as content type or correlation identifiers. Authentication headers such as `Authorization` are not included. * `Response Headers` records the HTTP headers returned by Frends in the response. This is useful for verifying caching, content negotiation, and other response metadata that the caller receives. * `Error Response Body` records the response body only when the request results in an error response. Logging error bodies is useful for diagnosing failures without capturing the full response payload on every successful call. * `Request Body` records the full body of the incoming request, up to the configured maximum length. This is useful for auditing or debugging the data that callers are sending, but should be used with care in environments where request payloads may contain sensitive data. * `Response Body` records the full body of the response returned by Frends, up to the configured maximum length. This is useful for verifying what data was returned to callers, particularly during development and testing. When either `Request Body` or `Response Body` is enabled, an additional field appears: `Body logging max length (KB)` controls the maximum size of the body captured per log entry. The available values are `1`, `10`, and `100` kilobytes. The default is `1`. Bodies exceeding the limit are truncated at the configured length. `IP Logging` is a separate dropdown that controls how the client IP address is recorded in the log entry. The options are: * `Client IP` records the direct TCP connection IP address — the IP of the host that opened the connection to the Agent. When callers connect directly without any intermediate proxy, this is the caller's real IP address. * `Client IP (X-Forwarded-For First)` records the leftmost IP address from the `X-Forwarded-For` request header, which is conventionally the originating client IP when requests pass through one or more proxies or load balancers. Use this option when your infrastructure consistently populates `X-Forwarded-For` and you trust the first value in the chain to represent the real caller. * `Client IP (X-Forwarded-For All)` records the entire `X-Forwarded-For` header value as-is, preserving the full chain of IP addresses from the originating client through every intermediate proxy. Use this option when you need a complete network path for auditing or debugging in complex infrastructure. * `Disable` turns off IP address logging entirely. No IP information is recorded in the log entry. This is appropriate for environments with privacy or data minimisation requirements that prohibit storing client IP addresses. The detail level can be set differently per logging configuration, so you can have more data captured in development and testing Agent Groups while limiting what is logged in production. ## Combining Policies API Policies support freely defined targeted endpoints, authentication identities, and logging options, which makes it possible to separate concerns into dedicated policies. A purely logging-specific policy can coexist alongside authentication policies. Different Agent Groups can each have their own policy covering the same endpoint, allowing you to apply different authentication methods, throttling limits, or logging settings per Agent Group. Each method and path combination — for example, `GET /api/example/v1/customers` — can only be covered by one policy per Agent Group. Frends validates this at save time and flags any overlap as a conflict. To accept multiple authentication methods on the same endpoint within the same Agent Group, add multiple identities to a single policy rather than creating separate policies. Starting from Frends version 6.3, a public access identity can also be combined with non-public ones in the same policy — requests carrying a valid credential are authenticated accordingly, while unauthenticated requests are handled as public access if the endpoint permits it. Note that API keys are scoped to a whole Environment rather than to a specific Agent Group, which can cause conflicts when separate policies exist for the same endpoint across multiple Agent Groups in the same Environment. In such cases, a private application token is a suitable alternative. ### Matching Priority Within a Policy If a single policy contains endpoint definitions that could overlap for the same incoming request, the tighter definition takes priority. When multiple definitions match, Frends resolves them in the following order. First, the more exact URL path wins regardless of the HTTP method defined. A path of `/api/test/v1/customers` takes priority over `/api/test` for any request to that sub-path. Second, when two rules share the same path, an explicit HTTP method such as `GET` or `POST` takes priority over an `ALL` wildcard rule at the same path. This means you can define a broad `ALL` rule covering an entire API path and then override it for specific sub-paths or methods within the same policy, without needing to split into multiple policies. ### Authentication Evaluation Order Frends API Policies support adding multiple authentication methods — such as OAuth, Private Application, and API Key — within a single policy, allowing different callers to authenticate using the method best suited to them without requiring separate policies for each. When a request arrives, Frends evaluates the credentials in a fixed order, but only for the methods that have been configured in the policy: 1. OAuth token 2. API Key 3. Public Access If a request includes a parseable OAuth token and OAuth is configured in the policy, that method is attempted and the result is final. An unparseable token is simply ignored and evaluation proceeds to the next configured method, or request is rejected with 401 Unauthorized error if there are no other methods configured. For example, if both OAuth and API Key are configured on the same policy: * A request carrying a valid OAuth token is authenticated via OAuth — the API Key check is skipped entirely. * A request carrying a valid OAuth token with insufficient claims is rejected — even if a valid API Key is also present in the request. * An unparseable or malformed OAuth token is ignored and evaluation proceeds to API Key. * A request with no OAuth token but a valid API Key is authenticated via API Key. If OAuth were not configured in the policy at all, but a valid OAuth token is still provided in the request, it may cause that the request is rejected with 403 Forbidden status code, even if a valid API Key is provided in the same request. As a final step in the authentication chain, if public access is enabled for the API operation and no other authentication methods were provided, the request will be allowed to go through. While the possible authentication methods are evaluated as a chain from Frends side, it does not enable the requestor to simply provide every authentication method at once and hope something passes. The system instead provides specifically alternative methods for requests to use. This approach is particularly useful when an API serves different types of consumers simultaneously, such as internal services authenticating via OAuth and external partners or legacy systems using API Keys, all under the same policy and endpoints. Note that if the Public Access toggle is enabled on a policy, it replaces all configured authentication methods for the targeted Agent Groups, so a separate policy should be used if authenticated access is still required for other groups. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frends.com/reference/api-management/api-policies.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.