openapi: 3.0.3
info:
  title: Aurora Solar Agreements Users & Tenants API
  description: 'The Aurora API lets you build apps and integrations on the Aurora Solar platform for solar sales and design. It is a tenant-scoped REST API: every resource lives under /tenants/{tenant_id}. Requests are authenticated with an API-key bearer token (Standard keys prefixed `sk_`, Restricted keys prefixed `rk_`; `sand_`/`prod_` denote the environment) passed as `Authorization: Bearer <token>`. The current API version is v2024.05, selected via the `Aurora-Version` request header.


    Scope note: A handful of paths in this document are confirmed directly against Aurora''s public reference (List Projects, Create Design Request, Create Webhook). The remaining paths are HONESTLY MODELED from Aurora''s published operation catalog (docs.aurorasolar.com/llms.txt) following the same `/tenants/{tenant_id}/<resource>` convention; exact path segments for modeled operations should be reconciled against the live reference, which is partially gated. Modeled operations carry `x-modeled: true`.'
  version: v2024.05
  contact:
    name: Aurora Solar Developer Platform
    url: https://docs.aurorasolar.com
  license:
    name: Proprietary
    url: https://aurorasolar.com/terms-of-service/
servers:
- url: https://api.aurorasolar.com
  description: Production
- url: https://api-sandbox.aurorasolar.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Users & Tenants
  description: Tenant, users, roles, teams, and SSO.
paths:
  /tenants/{tenant_id}/users:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    get:
      operationId: listUsers
      tags:
      - Users & Tenants
      summary: List users
      description: Lists the users in a tenant.
      x-modeled: true
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      tags:
      - Users & Tenants
      summary: Create a user
      description: Creates a user in a tenant.
      x-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /tenants/{tenant_id}/users/{user_id}:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - name: user_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: retrieveUser
      tags:
      - Users & Tenants
      summary: Retrieve a user
      description: Retrieves a single user.
      x-modeled: true
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateUser
      tags:
      - Users & Tenants
      summary: Update a user
      description: Updates a user, including activation state and role.
      x-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenant_id}:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    get:
      operationId: retrieveTenant
      tags:
      - Users & Tenants
      summary: Retrieve the tenant
      description: Retrieves the tenant record for the authenticated key.
      x-modeled: true
      responses:
        '200':
          description: The tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              detail:
                type: string
    Tenant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        created_at:
          type: string
          format: date-time
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
          - invited
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token.
      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:
    TenantId:
      name: tenant_id
      in: path
      required: true
      description: The tenant (organization) ID that owns the resource.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API-key bearer token. Standard keys are prefixed `sk_`, Restricted keys `rk_`; `sand_`/`prod_` denote sandbox vs production. Passed as `Authorization: Bearer <token>`.'