openapi: 3.1.0
info:
  title: Neon Management API Keys Auth API
  description: The Neon Management API is a RESTful interface for programmatically managing Neon serverless Postgres resources. It allows developers to create and manage projects, branches, databases, roles, compute endpoints, and operations. The API supports everything available through the Neon Console, enabling automation of database infrastructure workflows. An OpenAPI 3.0 specification is available along with TypeScript, Python, and Go SDKs.
  version: '2.0'
  contact:
    name: Neon Support
    url: https://neon.com/docs/introduction/support
  termsOfService: https://neon.com/terms-of-service
servers:
- url: https://console.neon.tech/api/v2
  description: Neon Production API
security:
- bearerAuth: []
tags:
- name: Auth
  description: Manage Neon Auth configuration for branches, including OAuth providers, webhooks, and authentication settings.
paths:
  /projects/{project_id}/branches/{branch_id}/auth:
    get:
      operationId: getProjectBranchAuth
      summary: Get Auth configuration
      description: Retrieves the Neon Auth configuration for the specified branch, including whether Auth is enabled, the Auth URL, and OAuth provider settings.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved Auth configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth:
                    $ref: '#/components/schemas/AuthConfig'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    put:
      operationId: updateProjectBranchAuth
      summary: Update Auth configuration
      description: Updates the Neon Auth configuration for the specified branch, including enabling or disabling Auth and configuring settings.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthConfigUpdate'
      responses:
        '200':
          description: Auth configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth:
                    $ref: '#/components/schemas/AuthConfig'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/auth/providers:
    get:
      operationId: listNeonAuthOAuthProviders
      summary: List OAuth providers
      description: Retrieves a list of configured OAuth providers for Neon Auth on the specified branch.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      responses:
        '200':
          description: Successfully retrieved list of OAuth providers
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthProvider'
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
    post:
      operationId: createNeonAuthOAuthProvider
      summary: Create an OAuth provider
      description: Configures a new OAuth provider for Neon Auth on the specified branch.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthProviderCreateRequest'
      responses:
        '201':
          description: OAuth provider created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    $ref: '#/components/schemas/OAuthProvider'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Branch not found
  /projects/{project_id}/branches/{branch_id}/auth/providers/{provider_id}:
    patch:
      operationId: updateNeonAuthOAuthProvider
      summary: Update an OAuth provider
      description: Updates the configuration for the specified OAuth provider.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      - name: provider_id
        in: path
        required: true
        description: The OAuth provider ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthProviderUpdateRequest'
      responses:
        '200':
          description: OAuth provider updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    $ref: '#/components/schemas/OAuthProvider'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: OAuth provider not found
    delete:
      operationId: deleteNeonAuthOAuthProvider
      summary: Delete an OAuth provider
      description: Removes the specified OAuth provider from Neon Auth configuration.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/projectIdParam'
      - $ref: '#/components/parameters/branchIdParam'
      - name: provider_id
        in: path
        required: true
        description: The OAuth provider ID
        schema:
          type: string
      responses:
        '200':
          description: OAuth provider deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: OAuth provider not found
components:
  parameters:
    projectIdParam:
      name: project_id
      in: path
      required: true
      description: The Neon project ID
      schema:
        type: string
    branchIdParam:
      name: branch_id
      in: path
      required: true
      description: The branch ID
      schema:
        type: string
  schemas:
    OAuthProviderUpdateRequest:
      type: object
      description: Request body for updating an OAuth provider
      properties:
        client_id:
          type: string
          description: The OAuth client ID
        client_secret:
          type: string
          description: The OAuth client secret
        enabled:
          type: boolean
          description: Whether this provider is enabled
    OAuthProvider:
      type: object
      description: An OAuth provider configuration for Neon Auth
      properties:
        id:
          type: string
          description: The OAuth provider ID
        provider:
          type: string
          description: The OAuth provider type (e.g., google, github, discord)
        client_id:
          type: string
          description: The OAuth client ID
        enabled:
          type: boolean
          description: Whether this provider is enabled
        created_at:
          type: string
          format: date-time
          description: Provider creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    OAuthProviderCreateRequest:
      type: object
      description: Request body for creating a new OAuth provider
      required:
      - provider
      - client_id
      - client_secret
      properties:
        provider:
          type: string
          description: The OAuth provider type
        client_id:
          type: string
          description: The OAuth client ID
        client_secret:
          type: string
          description: The OAuth client secret
        enabled:
          type: boolean
          description: Whether to enable this provider
          default: true
    AuthConfig:
      type: object
      description: Neon Auth configuration for a branch, providing managed authentication built on Better Auth.
      properties:
        enabled:
          type: boolean
          description: Whether Neon Auth is enabled for this branch
        auth_url:
          type: string
          format: uri
          description: The URL for the Neon Auth service
        jwks_url:
          type: string
          format: uri
          description: The JWKS URL for JWT validation
        schema:
          type: string
          description: The database schema used by Neon Auth (typically neon_auth)
    AuthConfigUpdate:
      type: object
      description: Request body for updating Auth configuration
      properties:
        enabled:
          type: boolean
          description: Whether to enable or disable Neon Auth
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Neon API keys are used to authenticate requests. Include the API key in the Authorization header as a Bearer token.
externalDocs:
  description: Neon API Documentation
  url: https://neon.com/docs/reference/api-reference