NextGen APIs

Integration API – Bearer Token Validation

How the bearer token sent to the Integration APIs (/api/integration/**) is validated, and how to configure, replace or disable the validation.

1. Overview

Two mechanisms can validate the token. Exactly one of them should be responsible for a given deployment.

Mechanism

Where it runs

Validates the token by

Spring Security

Standalone mode only (boot-starter)

Verifying the Cognito JWT (connector-security)

Private API token validation filter

Any deployment mode (standalone, Foundation, or a project using the api module as a library)

Calling a Foundation private API with the token: 2xx = valid

The private API validation is a plain servlet filter (BearerTokenValidationFilter). It does not need Spring Security, so it also works with Foundation.

2. Defaults per runtime

Runtime

integration-api.security.token-validation.enabled default

Who validates the token

Standalone mode (boot / projects on boot-starter)

false (shipped by the starter)

Spring Security (Cognito JWT)

Foundation (boot-foundation / boot-starter-foundation)

true

The private API filter

api module used as a library

true

The private API filter (projects that include boot-starter run in standalone mode and get false)

3. When to use the private API validation in standalone mode

Use it when the token cannot be validated against Cognito. In that case:

  1. Disable the Spring Security protection of the integration paths by making them public in the webhook chain of connector.security:

    YAML
    connector:
      security:
        webhook:
          enabled: true
          paths:
            - /api/integration/**
    
    

    The webhook chain is permit-all, so Spring Security no longer checks the token on these paths.

  2. Turn the private API validation on:

    YAML
    integration-api:
      security:
        token-validation:
          enabled: true
    
    

The filter runs right after the Spring Security filter chain, so it also applies to the paths the webhook chain leaves public.

Never make the paths public in the webhook chain without enabling the validation, otherwise the integration APIs are unprotected.

4. Configuration

Every property can be set as a Spring property or as a Foundation setup property (setup.properties) with the integrationlayer. prefix. If both are present, the Foundation setup property wins.

Property

Default

Description

integration-api.security.token-validation.enabled

see section 2

Registers the validation filter.

integration-api.security.token-validation.paths

/api/integration/**

Ant-style patterns, relative to the application context path, on which a bearer token is required.

integration-api.security.token-validation.url

/configurations/identity/r2/users/self

Private API called to validate the token. Either a path relative to the private API base URL, or an absolute URL.

integration-api.security.token-validation.method

GET

HTTP method used to call the URL.

integration-api.security.token-validation.timeout

10s

Maximum time to wait for the private API answer.

About the URL. A relative URL is resolved against the private API base URL (PRIVATE_API_BASEURL / integration-api.private.base-url), which normally already ends with /api. Write /configurations/identity/r2/users/self, not /api/configurations/identity/r2/users/self. An absolute URL ignores the base URL and must be written in full.

Spring (application.yml)

YAML
integration-api:
  security:
    token-validation:
      enabled: true
      paths: [ /api/integration/** ]
      url: /configurations/identity/r2/users/self
      method: GET
      timeout: 3s

Foundation (setup.properties)

integrationlayer.integration-api.security.token-validation.enabled=true
integrationlayer.integration-api.security.token-validation.paths=/api/integration/**
integrationlayer.integration-api.security.token-validation.url=/configurations/identity/r2/users/self
integrationlayer.integration-api.security.token-validation.method=GET
integrationlayer.integration-api.security.token-validation.timeout=10s

${env:...} and ${sys:...} lookups in setup properties are resolved at startup; lookups that need Foundation beans (e.g. ${awsSecret:...}) are not.

5. Validation flow and responses

  1. The request path is matched against paths (relative to the context path). Other paths are not touched.

  2. The Authorization: Bearer <token> header is read (the scheme is case-insensitive).

  3. The configured private API is called with the same Authorization: Bearer <token> header. The response body is ignored.

Situation

Response

Missing, blank or non-Bearer Authorization header

401 {"error":"Unauthorized"} – the private API is not called

Private API answers 2xx

The request continues

Private API answers 401 or 403

401 {"error":"Unauthorized"}

Any other status, timeout or connection error

503 {"error":"Token validation unavailable"}

A 503 means the validation service itself failed, not that the token is invalid: clients can safely retry.

6. Custom validation

To validate the token in a different way, declare a BearerTokenValidator bean. It replaces the default private API implementation (the url, method and timeout properties are then ignored; enabled and paths still apply).

Java
@Configuration
class MyTokenValidationConfig {

    @Bean
    BearerTokenValidator bearerTokenValidator(MyTokenService tokenService) {
        return token -> tokenService.isValid(token);
    }
}

Contract (BearerTokenValidator#isValid(String token)):

  • return true → valid, the request continues;

  • return false → invalid, the client receives 401;

  • throw BearerTokenValidationUnavailableException when no verdict can be given → the client receives 503.

7. Disabling the validation

Set integration-api.security.token-validation.enabled=false (or the integrationlayer. equivalent). The Foundation setup property takes precedence over the Spring one.

If enabled is true and url is explicitly blank, startup fails unless a custom BearerTokenValidator bean is declared.

8. Troubleshooting

Symptom

Likely cause

Always 401 even with a valid token

Wrong url/method, or the private API rejects the token; check the private API logs.

Always 503

Private API unreachable, timeout too short, or the URL resolves to a wrong path (e.g. a duplicated /api).

Calls without a token are accepted in standalone mode

The webhook chain makes the paths public and token-validation.enabled is still false (the standalone default).

Tests return 503

The test profile sends a token but the private API mock has no mapping for the validation URL: disable the validation in the test profile or stub the URL.

Setting has no effect on Foundation

Check the integrationlayer. prefix, and that setup.properties is loaded (geocall.setup.location / geocall.setup.file).