openapi: 3.0.0
info:
  title: Platform API (Beta)
  version: 1.0.0
  description: |
    **Private Preview** - Contact hey@useautumn.com to get access.

    The Platform API allows you to manage organizations and Stripe Connect accounts on behalf of your tenants. All endpoints require platform feature access.
servers:
  - url: https://api.useautumn.com/v1
security:
  - bearerAuth: []
paths:
  /platform/organizations:
    post:
      summary: Create Organization
      operationId: createPlatformOrganization
      description: Creates a new organization for a platform tenant. Reuses existing users and organizations if they already exist.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequest'
      responses:
        '201':
          description: Organization created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrganizationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Platform feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        - lang: curl
          source: |
            curl -X POST 'https://api.useautumn.com/v1/platform/organizations' \
            -H 'Authorization: Bearer am_sk_test_...' \
            -H 'Content-Type: application/json' \
            -d '{
              "user_email": "tenant@example.com",
              "name": "Tenant Organization",
              "slug": "tenant-org",
              "env": "both"
            }'
    get:
      summary: List Organizations
      operationId: listPlatformOrganizations
      description: Lists all organizations created by your master organization. Supports pagination.
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of organizations to return (1-100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of organizations to skip for pagination
      responses:
        '200':
          description: Organizations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrganizationsResponse'
        '403':
          description: Platform feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        - lang: curl
          source: |
            curl -X GET 'https://api.useautumn.com/v1/platform/organizations?limit=20&offset=0' \
            -H 'Authorization: Bearer am_sk_test_...'

  /platform/oauth_url:
    post:
      summary: Generate Stripe OAuth URL
      operationId: generateOAuthURL
      description: Generates a Stripe Connect OAuth URL for a platform organization. Use this to allow your tenants to connect their Stripe accounts.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateOAuthURLRequest'
      responses:
        '200':
          description: OAuth URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateOAuthURLResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        - lang: curl
          source: |
            curl -X POST 'https://api.useautumn.com/v1/platform/oauth_url' \
            -H 'Authorization: Bearer am_sk_test_...' \
            -H 'Content-Type: application/json' \
            -d '{
              "organization_slug": "tenant-org",
              "env": "test",
              "redirect_url": "https://yourapp.com/stripe/callback"
            }'

  /platform/organizations/stripe:
    post:
      summary: Update Connected Stripe Account
      operationId: updateStripeConfig
      description: Updates a platform organization's Stripe Connect configuration. Associates a Stripe account ID with the organization using your master Stripe credentials.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStripeConfigRequest'
      responses:
        '200':
          description: Stripe configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateStripeConfigResponse'
        '400':
          description: Invalid request parameters or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        - lang: curl
          source: |
            curl -X POST 'https://api.useautumn.com/v1/platform/organizations/stripe' \
            -H 'Authorization: Bearer am_sk_test_...' \
            -H 'Content-Type: application/json' \
            -d '{
              "organization_slug": "tenant-org",
              "test_account_id": "acct_1234567890",
              "live_account_id": "acct_0987654321"
            }'

  /platform/users:
    get:
      summary: List Users
      operationId: listPlatformUsers
      description: Lists all users created by your master organization. Supports pagination and optional expansion of related organizations.
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of users to return (1-100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of users to skip for pagination
        - name: expand
          in: query
          required: false
          schema:
            type: string
          description: "Comma-separated list of fields to expand. Currently supports: 'organizations'"
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsersResponse'
        '403':
          description: Platform feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        - lang: curl
          source: |
            curl -X GET 'https://api.useautumn.com/v1/platform/users?limit=20&offset=0&expand=organizations' \
            -H 'Authorization: Bearer am_sk_test_...'

components:
  schemas:
    CreateOrganizationRequest:
      type: object
      required:
        - user_email
        - name
        - slug
      properties:
        user_email:
          type: string
          format: email
          description: Email address of the organization owner. User will be created if it doesn't exist.
        name:
          type: string
          description: Display name for the organization.
        slug:
          type: string
          description: Unique slug for the organization.
        env:
          type: string
          enum:
            - test
            - live
            - both
          default: both
          description: Environment(s) to create API keys for.

    CreateOrganizationResponse:
      type: object
      properties:
        test_secret_key:
          type: string
          nullable: true
          description: Autumn test API key for the organization (if env is 'test' or 'both').
        live_secret_key:
          type: string
          nullable: true
          description: Autumn live API key for the organization (if env is 'live' or 'both').

    GenerateOAuthURLRequest:
      type: object
      required:
        - organization_slug
        - env
        - redirect_url
      properties:
        organization_slug:
          type: string
          description: The slug of the organization.
        env:
          type: string
          enum:
            - test
            - live
          description: "Environment: 'test' or 'live'."
        redirect_url:
          type: string
          format: uri
          description: URL to redirect to after OAuth completion.

    GenerateOAuthURLResponse:
      type: object
      properties:
        oauth_url:
          type: string
          format: uri
          description: Stripe Connect OAuth URL to redirect the user to.

    UpdateStripeConfigRequest:
      type: object
      required:
        - organization_slug
      properties:
        organization_slug:
          type: string
          description: The slug of the organization (without the org ID prefix).
        test_account_id:
          type: string
          description: Stripe account ID for test environment (e.g., acct_xxx).
        live_account_id:
          type: string
          description: Stripe account ID for live environment (e.g., acct_xxx).

    UpdateStripeConfigResponse:
      type: object
      properties:
        message:
          type: string
          description: Success message.
        organization:
          type: object
          properties:
            id:
              type: string
              description: Internal organization ID.
            slug:
              type: string
              description: Organization slug (without prefix).

    ListUsersResponse:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/PlatformUser'
        total:
          type: number
          description: Total number of users returned.
        limit:
          type: number
          description: Limit used in the query.
        offset:
          type: number
          description: Offset used in the query.

    PlatformUser:
      type: object
      properties:
        email:
          type: string
          format: email
          description: User's email address.
        created_at:
          type: number
          description: Timestamp (milliseconds since epoch) when the user was created.
        organizations:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PlatformOrganization'
          description: Array of organization objects (only if expand=organizations is set).

    ListOrganizationsResponse:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/PlatformOrganization'
        total:
          type: number
          description: Total number of organizations returned.
        limit:
          type: number
          description: Limit used in the query.
        offset:
          type: number
          description: Offset used in the query.

    PlatformOrganization:
      type: object
      properties:
        slug:
          type: string
          description: Organization slug (without master org prefix).
        name:
          type: string
          description: Organization name.
        created_at:
          type: number
          description: Timestamp (milliseconds since epoch) when the organization was created.

    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error description.
        code:
          type: string
          description: Error code.
          enum:
            - not_found
            - forbidden
            - invalid_input
            - internal_error
            - not_allowed

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Autumn API key with Bearer prefix