Supabase Projects API

openapi: 3.1.0
info:
  title: Supabase Auth Admin Projects API
  description: The Supabase Auth API (based on GoTrue) is a JWT-based API for managing users and issuing access tokens. It provides endpoints for user signup, signin with email/password, magic links, one-time passwords, OAuth social login, token refresh, user management, multi-factor authentication, and SAML-based single sign-on. When deployed on Supabase, the server requires an apikey header containing a valid Supabase-issued API key.
  version: 2.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/auth/v1
  description: Supabase Project Auth Server
  variables:
    project_ref:
      description: Your Supabase project reference ID
      default: your-project-ref
security:
- apiKeyAuth: []
tags:
- name: Projects
  description: Manage Supabase projects including creation, configuration, pausing, restoring, and deletion.
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List all projects
      description: Returns a list of all projects belonging to the authenticated user across all organizations.
      tags:
      - Projects
      responses:
        '200':
          description: Successfully retrieved list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing access token
    post:
      operationId: createProject
      summary: Create a new project
      description: Creates a new Supabase project within a specified organization. The project will be provisioned with a PostgreSQL database, Auth, Storage, and other services.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized
  /projects/{ref}:
    get:
      operationId: getProject
      summary: Get project details
      description: Retrieves detailed information about a specific project including its current status, region, database host, and configuration.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: Permanently deletes a Supabase project and all associated data including the database, storage files, and Edge Functions.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/api-keys:
    get:
      operationId: getProjectApiKeys
      summary: Get project API keys
      description: Retrieves the API keys (anon and service_role) for a specific project. These keys are used to authenticate requests to the project's APIs.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/health:
    get:
      operationId: getProjectHealth
      summary: Get project health status
      description: Returns the health status of all services in a project including the database, Auth, Storage, Realtime, and Edge Functions.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved health status
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceHealth'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/pause:
    post:
      operationId: pauseProject
      summary: Pause a project
      description: Pauses a Supabase project to stop incurring compute costs. The project database and services will become unavailable until restored.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project paused successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/restore:
    post:
      operationId: restoreProject
      summary: Restore a paused project
      description: Restores a previously paused project, making its database and services available again.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project restored successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
components:
  schemas:
    CreateProjectRequest:
      type: object
      required:
      - name
      - organization_id
      - plan
      - region
      - db_pass
      properties:
        name:
          type: string
          description: Display name for the new project
        organization_id:
          type: string
          description: ID of the organization to create the project in
        plan:
          type: string
          description: Billing plan for the project
          enum:
          - free
          - pro
          - team
          - enterprise
        region:
          type: string
          description: Cloud region for the project
        db_pass:
          type: string
          description: Password for the project database
          minLength: 6
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the project
        organization_id:
          type: string
          format: uuid
          description: ID of the organization that owns the project
        name:
          type: string
          description: Display name of the project
        region:
          type: string
          description: Cloud region where the project is hosted
          enum:
          - us-east-1
          - us-west-1
          - eu-west-1
          - eu-west-2
          - eu-central-1
          - ap-southeast-1
          - ap-southeast-2
          - ap-northeast-1
          - ap-south-1
          - sa-east-1
        created_at:
          type: string
          format: date-time
          description: Timestamp when the project was created
        database:
          $ref: '#/components/schemas/DatabaseConfig'
        status:
          type: string
          description: Current operational status of the project
          enum:
          - ACTIVE_HEALTHY
          - ACTIVE_UNHEALTHY
          - INACTIVE
          - INIT_FAILED
          - REMOVED
          - RESTORING
          - UPGRADING
          - PAUSING
          - COMING_UP
    DatabaseConfig:
      type: object
      properties:
        host:
          type: string
          description: Database host address
        version:
          type: string
          description: PostgreSQL version
    ApiKey:
      type: object
      properties:
        name:
          type: string
          description: Key name (anon or service_role)
          enum:
          - anon
          - service_role
        api_key:
          type: string
          description: The API key value
    ServiceHealth:
      type: object
      properties:
        name:
          type: string
          description: Name of the service
          enum:
          - database
          - auth
          - storage
          - realtime
          - functions
        healthy:
          type: boolean
          description: Whether the service is healthy
        status:
          type: string
          description: Detailed status message
  parameters:
    ProjectRef:
      name: ref
      in: path
      required: true
      description: The unique reference ID for the project, found in the project settings or URL.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Supabase project API key (anon key for public operations, service_role key for admin operations).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from a successful authentication.
externalDocs:
  description: Supabase Auth Documentation
  url: https://supabase.com/docs/guides/auth