> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nx1cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External authorization check (forward-auth / Envoy ext_authz)

> Forward-auth endpoint for an Envoy/nginx ``ext_authz`` filter.

Resolves the ``Authorization-PSK`` header (only) and translates a valid
**User** PSK into ``x-authz-*`` identity headers the proxy injects
upstream. Behaviour is intentionally PSK-driven so a Bearer-only request
falls through to downstream JWT validation:

* **User PSK present + valid** → ``200`` with ``x-authz-*`` + ``x-auth-method`` headers.
* **PSK present + invalid (or the shared general PSK)** → ``403``.
* **PSK absent** → ``200`` with **no** ``x-authz-*`` headers (JWT handles it).

The shared general PSK is rejected here: it carries no real identity, so it
must not be able to inject a fixed ``psk`` principal into upstream services.



## OpenAPI

````yaml get /api/identity/ext-authz
openapi: 3.1.0
info:
  title: Nx1 AI API
  description: |

    AI API for Nx1 Data Platform Management and Automated Data Tasks.

    Authentication is required via PSK in Authorization header.

    Default PSK is | [ask a friend] |
  version: 0.10.2
servers: []
security: []
paths:
  /api/identity/ext-authz:
    post:
      tags:
        - Identity
      summary: External authorization check (forward-auth / Envoy ext_authz)
      description: >-
        Forward-auth endpoint for an Envoy/nginx ``ext_authz`` filter.


        Resolves the ``Authorization-PSK`` header (only) and translates a valid

        **User** PSK into ``x-authz-*`` identity headers the proxy injects

        upstream. Behaviour is intentionally PSK-driven so a Bearer-only request

        falls through to downstream JWT validation:


        * **User PSK present + valid** → ``200`` with ``x-authz-*`` +
        ``x-auth-method`` headers.

        * **PSK present + invalid (or the shared general PSK)** → ``403``.

        * **PSK absent** → ``200`` with **no** ``x-authz-*`` headers (JWT
        handles it).


        The shared general PSK is rejected here: it carries no real identity, so
        it

        must not be able to inject a fixed ``psk`` principal into upstream
        services.
      operationId: ext_authz_api_identity_ext_authz_post
      responses:
        '200':
          description: Allowed — identity headers set when a valid PSK is present.
          content:
            application/json:
              schema: {}
        '403':
          description: PSK present but invalid.
      security:
        - APIKeyHeader: []
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization-PSK

````