openapi: 3.1.0
info:
  title: PlanetScale Platform Backups Passwords API
  description: The PlanetScale Platform API provides programmatic access to manage PlanetScale serverless MySQL-compatible databases. It allows developers to create and manage databases, branches, deploy requests, passwords, backups, service tokens, organization members, teams, bouncers, and billing data. The API supports authentication via service tokens and OAuth, enabling integration into CI/CD pipelines and infrastructure-as-code workflows.
  version: 1.0.0
  contact:
    name: PlanetScale Support
    url: https://support.planetscale.com
  termsOfService: https://planetscale.com/legal/tos
  license:
    name: Proprietary
    url: https://planetscale.com/legal/tos
servers:
- url: https://api.planetscale.com/v1
  description: PlanetScale Production API
security:
- serviceToken: []
tags:
- name: Passwords
  description: Manage branch passwords and connection credentials for connecting applications to database branches.
paths:
  /organizations/{organization}/databases/{database}/branches/{branch}/passwords:
    get:
      operationId: listPasswords
      summary: List passwords
      description: Returns a list of all passwords for a specific branch. Passwords are connection credentials used to connect to the branch.
      tags:
      - Passwords
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response with list of passwords
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Password'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createPassword
      summary: Create a password
      description: Creates a new password for a specific branch. The plaintext password is only returned once in the creation response.
      tags:
      - Passwords
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A descriptive name for the password.
                role:
                  type: string
                  description: The access role for the password.
                  enum:
                  - admin
                  - reader
                  - writer
                  - readwriter
                ttl:
                  type: number
                  description: Time to live in minutes. 0 means no expiration.
      responses:
        '201':
          description: Password created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordWithPlaintext'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization}/databases/{database}/branches/{branch}/passwords/{password_id}:
    get:
      operationId: getPassword
      summary: Get a password
      description: Returns details about a specific password. The plaintext password value is not included.
      tags:
      - Passwords
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/PasswordIdParam'
      responses:
        '200':
          description: Successful response with password details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Password'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePassword
      summary: Delete a password
      description: Deletes a password, revoking its access to the branch.
      tags:
      - Passwords
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/PasswordIdParam'
      responses:
        '204':
          description: Password deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization}/databases/{database}/branches/{branch}/passwords/{password_id}/renew:
    post:
      operationId: renewPassword
      summary: Renew a password
      description: Renews a password, extending its expiration time.
      tags:
      - Passwords
      parameters:
      - $ref: '#/components/parameters/OrganizationParam'
      - $ref: '#/components/parameters/DatabaseParam'
      - $ref: '#/components/parameters/BranchParam'
      - $ref: '#/components/parameters/PasswordIdParam'
      responses:
        '200':
          description: Password renewed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Password'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication failed. The service token or OAuth token is missing, invalid, or lacks the required permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request was well-formed but contains invalid parameters or violates business rules.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    BranchParam:
      name: branch
      in: path
      required: true
      description: The name of the branch.
      schema:
        type: string
    PerPageParam:
      name: per_page
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    OrganizationParam:
      name: organization
      in: path
      required: true
      description: The name of the organization.
      schema:
        type: string
    DatabaseParam:
      name: database
      in: path
      required: true
      description: The name of the database.
      schema:
        type: string
    PasswordIdParam:
      name: password_id
      in: path
      required: true
      description: The ID of the password.
      schema:
        type: string
  schemas:
    PasswordWithPlaintext:
      allOf:
      - $ref: '#/components/schemas/Password'
      - type: object
        properties:
          plain_text:
            type: string
            description: The plaintext password value. Only returned during creation.
          connection_strings:
            type: object
            description: Pre-formatted connection strings for various drivers.
            properties:
              general:
                type: string
                description: A general MySQL connection string.
              prisma:
                type: string
                description: A Prisma-formatted connection string.
              laravel:
                type: string
                description: A Laravel-formatted connection string.
              rails:
                type: string
                description: A Rails-formatted connection string.
    Password:
      type: object
      description: A connection password for a database branch.
      properties:
        id:
          type: string
          description: The unique identifier of the password.
        name:
          type: string
          description: The descriptive name of the password.
        role:
          type: string
          description: The access role for the password.
          enum:
          - admin
          - reader
          - writer
          - readwriter
        hostname:
          type: string
          description: The hostname for connecting with this password.
        username:
          type: string
          description: The username for connecting with this password.
        database_branch:
          type: string
          description: The branch this password is associated with.
        region:
          type: object
          description: The region for the connection.
          properties:
            slug:
              type: string
              description: The region slug.
            display_name:
              type: string
              description: The region display name.
        expires_at:
          type: string
          format: date-time
          description: The timestamp when the password expires. Null if no expiration.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the password was created.
        renewable:
          type: boolean
          description: Whether the password can be renewed.
    Error:
      type: object
      description: An error response from the PlanetScale API.
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.
  securitySchemes:
    serviceToken:
      type: apiKey
      in: header
      name: Authorization
      description: Service token authentication. Use the format 'ServiceToken {token_id}:{token_value}' in the Authorization header.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token authentication. Obtain tokens via the PlanetScale OAuth authorization code flow.
externalDocs:
  description: PlanetScale API Documentation
  url: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api