openapi: 3.1.0
info:
  title: Emissary-Ingress Configuration AuthService API
  description: Emissary-Ingress is a CNCF incubating Kubernetes-native API gateway and ingress controller built on the Envoy proxy. It is configured through Kubernetes Custom Resource Definitions (CRDs) including Mapping for request routing, Host for domain and TLS management, TLSContext for TLS termination settings, RateLimitService for delegating rate limiting to external services, and AuthService for external authentication. All resources are managed through the Kubernetes API server using standard CRUD operations.
  version: 3.9.0
  contact:
    name: Emissary-Ingress Community
    url: https://www.getambassador.io/community
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{kubernetes-api-server}
  description: Kubernetes API server
  variables:
    kubernetes-api-server:
      default: localhost:6443
      description: Address of the Kubernetes API server
tags:
- name: AuthService
  description: Operations for managing AuthService custom resources that configure external authentication and authorization services. Emissary-Ingress will call the configured auth service before forwarding requests to upstream services.
paths:
  /apis/getambassador.io/v3alpha1/namespaces/{namespace}/authservices:
    get:
      operationId: listNamespacedAuthService
      summary: Emissary-Ingress List AuthService resources in a namespace
      description: Returns all AuthService custom resources in the specified namespace. AuthService resources configure an external authentication and authorization service that Emissary-Ingress calls before forwarding requests to upstream backend services.
      tags:
      - AuthService
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: Successfully retrieved list of AuthService resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthServiceList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createNamespacedAuthService
      summary: Emissary-Ingress Create an AuthService resource
      description: Creates a new AuthService custom resource in the specified namespace configuring the external authentication service URL, protocol, timeout, allowed request headers, and allowed authorization headers.
      tags:
      - AuthService
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthService'
      responses:
        '201':
          description: AuthService resource created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthService'
        '400':
          description: Invalid AuthService specification
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    AuthServiceSpec:
      type: object
      description: Specification for the AuthService.
      required:
      - auth_service
      properties:
        auth_service:
          type: string
          description: Name (and optional port) of the Kubernetes service providing external authentication.
          example: auth-service:3000
        path_prefix:
          type: string
          description: Path prefix to prepend to the auth service path when making authentication requests.
        timeout_ms:
          type: integer
          description: Timeout in milliseconds for authentication service calls. If the service does not respond in time, the request is rejected.
          minimum: 0
          default: 5000
        tls:
          type: string
          description: Name of a TLSContext to use when connecting to the auth service over TLS.
        proto:
          type: string
          description: Protocol to use when calling the auth service.
          enum:
          - http
          - grpc
          default: http
        allowed_request_headers:
          type: array
          description: Request headers to forward to the auth service. All headers not in this list are stripped before the auth request is made.
          items:
            type: string
        allowed_authorization_headers:
          type: array
          description: Headers from the auth service response to forward to the upstream service on successful authorization.
          items:
            type: string
        include_body:
          type: object
          description: Configuration for forwarding the request body to the auth service.
          properties:
            max_bytes:
              type: integer
              description: Maximum number of request body bytes to send to the auth service.
              minimum: 0
            allow_partial:
              type: boolean
              description: If true, send a partial body when the request body exceeds max_bytes. If false, fail if the body is too large.
        failure_mode_allow:
          type: boolean
          description: If true, requests proceed even if the auth service is unavailable. Defaults to false.
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the resource, unique within the namespace.
          maxLength: 253
        namespace:
          type: string
          description: Namespace the resource belongs to.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values for organizing resources.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Map of non-identifying metadata for the resource.
        resourceVersion:
          type: string
          description: Opaque value used for optimistic concurrency control. Must be provided on update and delete operations.
        generation:
          type: integer
          format: int64
          description: Monotonically increasing sequence number for desired state changes.
        uid:
          type: string
          description: Unique identifier assigned by the Kubernetes system.
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp when the resource was created.
    AuthService:
      type: object
      description: Emissary-Ingress AuthService custom resource configuring an external authentication and authorization service. Before forwarding a request to the upstream service, Emissary-Ingress sends the request to the configured auth service which can approve, reject, or modify the request.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          description: API version of the resource.
          enum:
          - getambassador.io/v3alpha1
        kind:
          type: string
          description: Resource kind.
          enum:
          - AuthService
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/AuthServiceSpec'
    AuthServiceList:
      type: object
      description: List of AuthService resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - AuthServiceList
        metadata:
          type: object
        items:
          type: array
          description: List of AuthService resources.
          items:
            $ref: '#/components/schemas/AuthService'
  parameters:
    namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace of the resource.
      schema:
        type: string
    continueToken:
      name: continue
      in: query
      required: false
      description: A continuation token for paginating through large result sets, returned from a previous list call.
      schema:
        type: string
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: A selector to restrict the list of returned resources by their labels. Defaults to everything.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of responses to return per page. If there are additional results, a continue token is returned.
      schema:
        type: integer
        minimum: 1
externalDocs:
  description: Emissary-Ingress Documentation
  url: https://www.getambassador.io/docs/emissary/