openapi: 3.2.0
info:
  title: Oxide Region Silos API
  description: API for interacting with the Oxide control plane
  contact:
    url: https://oxide.computer
    email: api@oxide.computer
  version: 2026081901.0.0
tags:
- name: silos
  description: Silos represent a logical partition of users and resources.
  externalDocs:
    url: http://docs.oxide.computer/api/silos
paths:
  /v1/auth-settings:
    get:
      tags:
      - silos
      summary: Fetch current silo's auth settings
      operationId: auth_settings_view
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiloAuthSettings'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
    put:
      tags:
      - silos
      summary: Update current silo's auth settings
      operationId: auth_settings_update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiloAuthSettingsUpdate'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiloAuthSettings'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/certificates:
    get:
      tags:
      - silos
      summary: List certificates for external endpoints
      description: Returns a list of TLS certificates used for the external API (for the current Silo).  These are sorted by creation date, with the most recent certificates appearing first.
      operationId: certificate_list
      parameters:
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/NameOrIdSortMode'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
    post:
      tags:
      - silos
      summary: Create system-wide x.509 certificate
      description: This certificate is automatically used by the Oxide Control plane to serve external connections.
      operationId: certificate_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateCreate'
        required: true
      responses:
        '201':
          description: successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/certificates/{certificate}:
    get:
      tags:
      - silos
      summary: Fetch certificate
      description: Returns the details of a specific certificate
      operationId: certificate_view
      parameters:
      - in: path
        name: certificate
        description: Name or ID of the certificate
        required: true
        schema:
          $ref: '#/components/schemas/NameOrId'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - silos
      summary: Delete certificate
      description: Permanently delete a certificate. This operation cannot be undone.
      operationId: certificate_delete
      parameters:
      - in: path
        name: certificate
        description: Name or ID of the certificate
        required: true
        schema:
          $ref: '#/components/schemas/NameOrId'
      responses:
        '204':
          description: successful deletion
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/groups:
    get:
      tags:
      - silos
      summary: List groups
      operationId: group_list
      parameters:
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/IdSortMode'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
  /v1/groups/{group_id}:
    get:
      tags:
      - silos
      summary: Fetch group
      operationId: group_view
      parameters:
      - in: path
        name: group_id
        description: ID of the group
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/policy:
    get:
      tags:
      - silos
      summary: Fetch current silo's IAM policy
      operationId: policy_view
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiloRolePolicy'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
    put:
      tags:
      - silos
      summary: Update current silo's IAM policy
      operationId: policy_update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiloRolePolicy'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiloRolePolicy'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/users:
    get:
      tags:
      - silos
      summary: List users
      operationId: user_list
      parameters:
      - in: query
        name: group
        schema:
          type:
          - string
          - 'null'
          format: uuid
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/IdSortMode'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
  /v1/users/{user_id}:
    get:
      tags:
      - silos
      summary: Fetch user
      operationId: user_view
      parameters:
      - in: path
        name: user_id
        description: ID of the user
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/users/{user_id}/access-tokens:
    get:
      tags:
      - silos
      summary: List user's access tokens
      operationId: user_token_list
      parameters:
      - in: path
        name: user_id
        description: ID of the user
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/IdSortMode'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAccessTokenResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
  /v1/users/{user_id}/logout:
    post:
      tags:
      - silos
      summary: Log user out
      description: Silo admins can use this endpoint to log the specified user out by deleting all of their tokens AND sessions. This cannot be undone.
      operationId: user_logout
      parameters:
      - in: path
        name: user_id
        description: ID of the user
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: resource updated
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/users/{user_id}/sessions:
    get:
      tags:
      - silos
      summary: List user's console sessions
      operationId: user_session_list
      parameters:
      - in: path
        name: user_id
        description: ID of the user
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/IdSortMode'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleSessionResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
  /v1/utilization:
    get:
      tags:
      - silos
      summary: Fetch resource utilization for user's current silo
      operationId: utilization_view
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Utilization'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  schemas:
    UserResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/User'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    SiloRolePolicy:
      description: 'Policy for a particular resource


        Note that the Policy only describes access granted explicitly for this resource.  The policies of parent resources can also cause a user to have access to this resource.'
      type: object
      properties:
        role_assignments:
          description: Roles directly assigned on this resource
          type: array
          items:
            $ref: '#/components/schemas/SiloRoleRoleAssignment'
      required:
      - role_assignments
    Utilization:
      description: View of the current silo's resource utilization and capacity
      type: object
      properties:
        capacity:
          description: The total amount of resources that can be provisioned in this silo. Actions that would exceed this limit will fail.
          allOf:
          - $ref: '#/components/schemas/VirtualResourceCounts'
        provisioned:
          description: 'Accounts for resources allocated to running instances or storage allocated via disks or snapshots.


            Note that CPU and memory resources associated with stopped instances are not counted here, whereas associated disks will still be counted.'
          allOf:
          - $ref: '#/components/schemas/VirtualResourceCounts'
      required:
      - capacity
      - provisioned
    CertificateResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    IdentityType:
      description: Describes what kind of identity is described by an id
      type: string
      enum:
      - silo_user
      - silo_group
    NameOrIdSortMode:
      description: Supported set of sort modes for scanning by name or id
      oneOf:
      - description: Sort in increasing order of "name"
        type: string
        enum:
        - name_ascending
      - description: Sort in decreasing order of "name"
        type: string
        enum:
        - name_descending
      - description: Sort in increasing order of "id"
        type: string
        enum:
        - id_ascending
    IdSortMode:
      description: 'Supported set of sort modes for scanning by id only.


        Currently, we only support scanning in ascending order.'
      oneOf:
      - description: Sort in increasing order of "id"
        type: string
        enum:
        - id_ascending
    SiloAuthSettingsUpdate:
      description: Updateable properties of a silo's settings.
      type: object
      properties:
        device_token_max_ttl_seconds:
          description: Maximum lifetime of a device token in seconds. If set to null, users will be able to create tokens that do not expire.
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      required:
      - device_token_max_ttl_seconds
    ServiceUsingCertificate:
      description: The service intended to use this certificate.
      oneOf:
      - description: This certificate is intended for access to the external API.
        type: string
        enum:
        - external_api
    ByteCount:
      description: Byte count to express memory or storage capacity.
      type: integer
      format: uint64
      minimum: 0
    Error:
      description: Error information from a response.
      type: object
      properties:
        error_code:
          type: string
        message:
          type: string
        request_id:
          type: string
      required:
      - message
      - request_id
    DeviceAccessTokenResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/DeviceAccessToken'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    Group:
      description: View of a Group
      type: object
      properties:
        display_name:
          description: Human-readable name that can identify the group
          type: string
        id:
          type: string
          format: uuid
        silo_id:
          description: Uuid of the silo to which this group belongs
          type: string
          format: uuid
        time_created:
          description: Timestamp when this group was created
          type: string
          format: date-time
        time_modified:
          description: Timestamp when this group was last modified
          type: string
          format: date-time
      required:
      - display_name
      - id
      - silo_id
      - time_created
      - time_modified
    Certificate:
      description: View of a Certificate
      type: object
      properties:
        cert:
          description: PEM-formatted string containing public certificate chain
          type: string
        description:
          description: Human-readable free-form text about a resource
          type: string
        id:
          description: Unique, immutable, system-controlled identifier for each resource
          type: string
          format: uuid
        name:
          description: Unique, mutable, user-controlled identifier for each resource
          allOf:
          - $ref: '#/components/schemas/Name'
        service:
          description: The service using this certificate
          allOf:
          - $ref: '#/components/schemas/ServiceUsingCertificate'
        time_created:
          description: Timestamp when this resource was created
          type: string
          format: date-time
        time_modified:
          description: Timestamp when this resource was last modified
          type: string
          format: date-time
      required:
      - cert
      - description
      - id
      - name
      - service
      - time_created
      - time_modified
    ConsoleSession:
      description: View of a console session
      type: object
      properties:
        id:
          description: A unique, immutable, system-controlled identifier for the session
          type: string
          format: uuid
        time_created:
          type: string
          format: date-time
        time_last_used:
          type: string
          format: date-time
      required:
      - id
      - time_created
      - time_last_used
    SiloRoleRoleAssignment:
      description: 'Describes the assignment of a particular role on a particular resource to a particular identity (user, group, etc.)


        The resource is not part of this structure.  Rather, `RoleAssignment`s are put into a `Policy` and that Policy is applied to a particular resource.'
      type: object
      properties:
        identity_id:
          type: string
          format: uuid
        identity_type:
          $ref: '#/components/schemas/IdentityType'
        role_name:
          $ref: '#/components/schemas/SiloRole'
      required:
      - identity_id
      - identity_type
      - role_name
    SiloAuthSettings:
      description: View of silo authentication settings
      type: object
      properties:
        device_token_max_ttl_seconds:
          description: Maximum lifetime of a device token in seconds. If set to null, users will be able to create tokens that do not expire.
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 0
        silo_id:
          type: string
          format: uuid
      required:
      - silo_id
    ConsoleSessionResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/ConsoleSession'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    NameOrId:
      oneOf:
      - title: id
        allOf:
        - type: string
          format: uuid
      - title: name
        allOf:
        - $ref: '#/components/schemas/Name'
    DeviceAccessToken:
      description: View of a device access token
      type: object
      properties:
        id:
          description: 'A unique, immutable, system-controlled identifier for the token.


            Note that this ID is not the bearer token itself, which starts with "oxide-token-".'
          type: string
          format: uuid
        time_created:
          type: string
          format: date-time
        time_expires:
          description: Expiration timestamp. A null value means the token does not automatically expire.
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - time_created
    CertificateCreate:
      description: Create-time parameters for a `Certificate`
      type: object
      properties:
        cert:
          description: PEM-formatted string containing public certificate chain
          type: string
        description:
          type: string
        key:
          description: PEM-formatted string containing private key
          type: string
        name:
          $ref: '#/components/schemas/Name'
        service:
          description: The service using this certificate
          allOf:
          - $ref: '#/components/schemas/ServiceUsingCertificate'
      required:
      - cert
      - description
      - key
      - name
      - service
    Name:
      title: A name unique within the parent collection
      description: Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.
      type: string
      pattern: ^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$
      minLength: 1
      maxLength: 63
    GroupResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/Group'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    User:
      description: View of a User
      type: object
      properties:
        display_name:
          description: Human-readable name that can identify the user
          type: string
        id:
          type: string
          format: uuid
        silo_id:
          description: Uuid of the silo to which this user belongs
          type: string
          format: uuid
        time_created:
          description: Timestamp when this user was created
          type: string
          format: date-time
        time_modified:
          description: Timestamp when this user was last modified
          type: string
          format: date-time
      required:
      - display_name
      - id
      - silo_id
      - time_created
      - time_modified
    SiloRole:
      type: string
      enum:
      - admin
      - collaborator
      - limited_collaborator
      - viewer
    VirtualResourceCounts:
      description: A collection of resource counts used to describe capacity and utilization
      type: object
      properties:
        cpus:
          description: Number of virtual CPUs
          type: integer
          format: int64
        memory:
          description: Amount of memory in bytes
          allOf:
          - $ref: '#/components/schemas/ByteCount'
        storage:
          description: Amount of disk storage in bytes
          allOf:
          - $ref: '#/components/schemas/ByteCount'
      required:
      - cpus
      - memory
      - storage
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'