Security Schemes

Relixy reads security scheme definitions from your OpenAPI spec and automatically injects the corresponding credentials into every upstream request. Credentials are configured via the x-rely-security-credentials vendor extension.

info

Security schemes described here are for outbound authentication — how Relixy authenticates itself to upstream APIs. For inbound authentication — how clients authenticate to Relixy — see RelyAuth.

Supported scheme types

Type	OpenAPI type	Description
API Key	apiKey	Static key sent in a header, query parameter, or cookie
HTTP Bearer	http (scheme: bearer)	Static token sent as a Bearer token in a header
HTTP Basic	http (scheme: basic)	Username and password via HTTP Basic auth
OAuth2 Client Credentials	oauth2	Full OAuth2 client credentials flow with token refresh
Mutual TLS	mutualTLS	Configure TLS in the HTTP client setting

Configuring credentials

Add x-rely-security-credentials as an extension on the security scheme or flow object. You can supply literals or environment variable names for values.

API Key

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    components:
      securitySchemes:
        ApiKeyAuth:
          type: apiKey
          in: header # header | query | cookie
          name: X-Api-Key
          x-rely-security-credentials:
            apiKey:
              env: UPSTREAM_API_KEY

The in and name fields from the OpenAPI spec control where the key is placed.

HTTP Bearer

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    components:
      securitySchemes:
        BearerAuth:
          type: http
          scheme: bearer
          x-rely-security-credentials:
            apiKey:
              value: "my-static-token"

HTTP Basic

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    components:
      securitySchemes:
        BasicAuth:
          type: http
          scheme: basic
          x-rely-security-credentials:
            username:
              env: UPSTREAM_USERNAME
            password:
              env: UPSTREAM_PASSWORD

OAuth2

Client Credentials

Credentials for the OAuth2 flow are placed on the clientCredentials flow object:

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    components:
      securitySchemes:
        OAuth2Auth:
          type: oauth2
          flows:
            clientCredentials:
              tokenUrl: "https://auth.example.com/oauth/token"
              scopes:
                read:data: "Read access"
              x-rely-security-credentials:
                clientId:
                  env: OAUTH2_CLIENT_ID
                clientSecret:
                  env: OAUTH2_CLIENT_SECRET
                # Optional extra query params for the token endpoint
                endpointParams:
                  audience:
                    value: "https://api.example.com"

Dynamic token URL

If the token URL changes between environments, use x-rely-oauth2-token-url-env to load it from an environment variable:

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    components:
      securitySchemes:
        OAuth2Auth:
          type: oauth2
          flows:
            clientCredentials:
              tokenUrl: "https://default-auth.example.com/token"
              x-rely-oauth2-token-url-env: OAUTH2_TOKEN_URL
              x-rely-oauth2-refresh-url-env: OAUTH2_REFRESH_URL
              x-rely-security-credentials:
                clientId:
                  env: OAUTH2_CLIENT_ID
                clientSecret:
                  env: OAUTH2_CLIENT_SECRET

Extension	Description
x-rely-oauth2-token-url-env	Environment variable containing the token endpoint URL. Overrides tokenUrl when set.
x-rely-oauth2-refresh-url-env	Environment variable containing the refresh endpoint URL.

Applying security to operations

Global security requirements are defined at the document level and apply to all operations by default. Per-operation security requirements override the global ones.

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  spec:
    # Global security — applies to all operations unless overridden
    security:
      - OAuth2Auth:
          - read:data

    paths:
      /public:
        get:
          summary: "Public endpoint — no auth"
          security: [] # empty array = no authentication for this operation

      /data:
        get:
          summary: "Uses the global OAuth2 scheme"

      /admin:
        post:
          summary: "Uses a different scheme"
          security:
            - ApiKeyAuth: []

Per-server security

You can apply different security schemes to specific upstream servers using the x-rely-server-security-schemes extension on a server object:

servers:
  - url: "https://api-primary.example.com"
    x-rely-server-security:
      OAuth2Auth: []
  - url: "https://api-secondary.example.com"
    x-rely-server-security:
      ApiKeyAuth: []

Forwarding headers

For other security schemes which don't support machine-to-machine authentication, and access tokens can be sent from the client. You can forward headers from the client to remote services by the settings.forwardHeaders.request setting:

version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  settings:
    forwardHeaders:
      request:
        - Authorization
  # ...