openapi: 3.0.1
info:
  title: Enseada
  description: A Cloud native multi-package registry
  x-logo:
    url: https://enseada.io/images/enseada-logo.png
    backgroundColor: "#FFFFFF"
    altText: Enseada logo
  contact:
    email: enseada@pm.me
    url: https://enseada.io
  license:
    name: MPL 2.0
    url: https://opensource.org/licenses/MPL-2.0
  version: 0.1.0
externalDocs:
  description: Find out more about Enseada
  url: https://enseada.io
tags:
  - name: docker
    description: Docker V2 registry endpoints
  - name: monitoring
    description: Monitoring and observability endpoints
  - name: rbac
    description: RBAC management endpoints
  - name: users
    description: User management endpoints
paths:
  /api/v1beta1/users:
    get:
      tags:
        - users
      summary: List registered users
      operationId: user::list
      x-required-permissions:
        - object: users
          action: read
      security:
        - oauth:
            - users:read
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PageInfo"
                  - type: object
                    properties:
                      items:
                        type: array
                        uniqueItems: true
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/User"
    post:
      tags:
        - users
      summary: Register a new user
      operationId: user::register
      x-required-permissions:
        - object: users
          action: create
      security:
        - oauth:
            - users:manage
      requestBody:
        required: true
        description: New user login information
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegistrationInfo"
      responses:
        "200":
          description: New user details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "409":
          description: A user with the given username already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  "/api/v1beta1/users/{username}":
    parameters:
      - name: username
        in: path
        description: Username of the desired user
        required: true
        schema:
          type: string
    get:
      tags:
        - users
      summary: Fetch a single user details
      operationId: user::get
      x-required-permissions:
        - object: user:$username
          action: read
      security:
        - oauth:
            - users:read
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    put:
      tags:
        - users
      summary: Edit a user
      operationId: user::update
      x-required-permissions:
        - object: user:$username
          action: update
        - object: user:$username
          action: disable
          description: only required to change the `enabled` status
      security:
        - oauth:
            - users:manage
      requestBody:
        required: true
        description: User information to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserEdit"
      responses:
        "200":
          description: Updated user details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    delete:
      tags:
        - users
      summary: Delete a user
      operationId: user::delete
      x-required-permissions:
        - object: user:$username
          action: delete
      security:
        - oauth:
            - users:manage
      responses:
        "200":
          description: Deleted user details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  "/api/v1beta1/users/{username}/permissions":
    parameters:
      - $ref: "#/components/parameters/username"
    get:
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      tags:
        - users
        - rbac
      summary: Fetch a user's permissions
      operationId: rbac::get_user_permissions
      x-required-permissions:
        - object: user:$username
          action: read_permissions
      security:
        - oauth:
            - users:read
            - permissions
      responses:
        "200":
          description: User permissions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PageInfo"
                  - type: object
                    properties:
                      items:
                        type: array
                        uniqueItems: true
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    post:
      tags:
        - users
        - rbac
      summary: Add a permission to the user
      operationId: rbac::add_user_permission
      x-required-permissions:
        - object: user:$username
          action: manage_permissions
      security:
        - oauth:
            - users:read
            - permissions
      requestBody:
        description: The new permission
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: The newly created permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "409":
          description: The user already has this permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    delete:
      tags:
        - users
        - rbac
      summary: Remove a permission to the user
      operationId: rbac::remove_user_permission
      x-required-permissions:
        - object: user:$username
          action: manage_permissions
      security:
        - oauth:
            - users:read
            - permissions
      requestBody:
        description: The permission to remove
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: The removed permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: |
            Either user with the given username doesn't exist,
            or it does not have the given permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  "/api/v1beta1/users/{username}/roles":
    parameters:
      - $ref: "#/components/parameters/username"
    get:
      tags:
        - users
        - rbac
      summary: Fetch a user's roles
      operationId: rbac::get_user_roles
      x-required-permissions:
        - object: user:$username
          action: read_roles
      security:
        - oauth:
            - users:read
            - roles
      responses:
        "200":
          description: User roles details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PageInfo"
                  - type: object
                    properties:
                      items:
                        type: array
                        uniqueItems: true
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/Role"
  "/api/v1beta1/users/{username}/roles/{role}":
    parameters:
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/role'
    put:
      tags:
        - users
        - rbac
      summary: Add a role to the user
      operationId: rbac::add_user_role
      x-required-permissions:
        - object: user:$username
          action: manage_roles
      security:
        - oauth:
            - users:manage
            - roles
      responses:
        "200":
          description: Updated user role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    delete:
      tags:
        - users
        - rbac
      summary: Remove a role from the user
      operationId: rbac::remove_user_role
      x-required-permissions:
        - object: user:$username
          action: manage_roles
      security:
        - oauth:
            - users:manage
            - roles
      responses:
        "200":
          description: Delete user role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A user with the given username doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  /api/v1beta1/users/me:
    get:
      tags:
        - users
      summary: Fetches information about the currently authenticated user
      operationId: user::me
      security:
        - oauth:
            - profile
      responses:
        "200":
          description: Current user details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  "/api/v1beta1/roles/{role}/permissions":
    parameters:
      - $ref: "#/components/parameters/role"
    get:
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      tags:
        - rbac
      summary: Fetch a role's permissions
      operationId: rbac::get_role_permissions
      x-required-permissions:
        - object: role:$role
          action: read_permissions
      security:
        - oauth:
            - roles
            - permissions
      responses:
        "200":
          description: Role permissions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PageInfo"
                  - type: object
                    properties:
                      items:
                        type: array
                        uniqueItems: true
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A role with the given name doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    post:
      tags:
        - rbac
      summary: Add a permission to the role
      operationId: rbac::add_role_permission
      x-required-permissions:
        - object: role:$role
          action: manage_permissions
      security:
        - oauth:
            - roles
            - permissions
      requestBody:
        description: The new permission
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: The newly created permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A role with the given name doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "409":
          description: The role already has this permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    delete:
      tags:
        - rbac
      summary: Remove a permission from the role
      operationId: rbac::remove_role_permission
      x-required-permissions:
        - object: role:$role
          action: manage_permissions
      security:
        - oauth:
            - roles
            - permissions
      requestBody:
        description: The permission to remove
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Permission"
      responses:
        "200":
          description: The removed permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: |
            Either a role with the given name doesn't exist,
            or it does not have the given permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  /api/v1beta1/clients:
    get:
      tags:
        - clients
      summary: List registered clients
      operationId: client::list
      x-required-permissions:
        - object: clients
          action: read
      security:
        - oauth:
            - clients:read
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: List of clients
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PageInfo"
                  - type: object
                    properties:
                      items:
                        type: array
                        uniqueItems: true
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/Client"
    post:
      tags:
        - clients
      summary: Register a new client
      operationId: client::register
      x-required-permissions:
        - object: clients
          action: create
      security:
        - oauth:
            - clients:manage
      requestBody:
        required: true
        description: New client login information
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Client"
      responses:
        "200":
          description: New client details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Client"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "409":
          description: A client with the given client ID already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  "/api/v1beta1/clients/{client_id}":
    parameters:
      - name: client_id
        in: path
        description: Client ID of the desired client
        required: true
        schema:
          type: string
    get:
      tags:
        - clients
      summary: Fetch a single client details
      operationId: client::get
      x-required-permissions:
        - object: client:$client_id
          action: read
      security:
        - oauth:
            - clients:read
      responses:
        "200":
          description: Client details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Client"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A client with the given client ID doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    put:
      tags:
        - clients
      summary: Edit a client
      operationId: client::update
      x-required-permissions:
        - object: client:$client_id
          action: update
        - object: client:$client_id
          action: disable
          description: only required to change the `enabled` status
      security:
        - oauth:
            - clients:manage
      requestBody:
        required: true
        description: Client information to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientEdit"
      responses:
        "200":
          description: Updated client details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Client"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A client with the given client ID doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
    delete:
      tags:
        - clients
      summary: Delete a client
      operationId: client::delete
      x-required-permissions:
        - object: client:$client_id
          action: delete
      security:
        - oauth:
            - clients:manage
      responses:
        "200":
          description: Deleted client details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Client"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
        "404":
          description: A client with the given client ID doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
  /health:
    get:
      tags:
        - monitoring
      summary: Get the server health status
      operationId: health::get
      responses:
        "200":
          description: Server is active
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: Server is not active
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
components:
  parameters:
    cursor:
      name: cursor
      in: query
      description: |
        Opaque cursor used for pagination.
        Can be obtained from the `next_cursor` field in PageInfo.
      required: false
      schema:
        type: string
        format: base64
      example: V2h5IGFyZSB5b3UgdHJ5aW5nIHRvIGRlY29kZSBhIGN1cnNvcj8gSSB0b2xkIHlvdSBpdCB3YXMgb3BhcXVlIDopCg==
    limit:
      name: limit
      in: query
      description: Numbers of items to return when paginating.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
    username:
      name: username
      in: path
      description: Username of the desired user
      required: true
      schema:
        type: string
    role:
      name: role
      in: path
      description: Role name
      required: true
      schema:
        type: string
  schemas:
    User:
      type: object
      required:
        - username
      properties:
        username:
          type: string
        enabled:
          type: boolean
          description: If false, the user is not able to authenticate
          default: true
    UserEdit:
      type: object
      properties:
        enabled:
          type: boolean
          description: If false, the user is not able to authenticate
    UserRegistrationInfo:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
        roles:
          type: array
          description: Default roles for the new user
          example:
            - - admin
          items:
            type: string
            minItems: 0
    Role:
      type: object
      properties:
        role:
          type: string
          description: The user's role
      example:
        role: users:manage
    Permission:
      type: object
      required:
        - object
        - action
      description: A permission represented in the traditional subject-object-action tuple.
      properties:
        subject:
          type: string
          format: guid
          description: |
            The subject the permission is granted to.
            Can be omitted in relative paths like `/users/{username}/permissions` as it will be
            overwritten by the relative subject itself.
          example: user:root
        object:
          type: string
          format: guid
          description: The object this permission is granted over
          example: docker_image:example
        action:
          type: string
          description: The action that is permitted on the object
          example: read
    Client:
      type: object
      required:
        - client_id
        - kind
        - allowed_scopes
        - allowed_redirect_uris
      properties:
        client_id:
          type: string
        client_secret:
          type: string
          description: Required for clients with kind 'confidential'
        kind:
          type: string
          enum:
            - public
            - confidential
        allowed_scopes:
          type: string
        allowed_redirect_uris:
          type: array
          items:
            type: string
    ClientEdit:
      type: object
      properties:
        client_secret:
          type: string
        allowed_scopes:
          type: string
        allowed_redirect_uris:
          type: array
          items:
            type: string
    HealthResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - ok
    APIError:
      type: object
      required:
        - error
        - reasons
      properties:
        error:
          type: string
          description: Canonical reason for the error
          example: Error Name
        reasons:
          type: array
          items:
            type: string
          example:
            - an error has occurred
    PageInfo:
      type: object
      description: Pagination info
      required:
        - count
        - next_cursor
      properties:
        count:
          type: integer
          minimum: 0
          description: Number of items in the current page
        next_cursor:
          type: string
          description: |
            Opaque cursor to access the next page.
            Can be `null` if there are no more pages
          x-nullable: true
          example: V2h5IGFyZSB5b3UgdHJ5aW5nIHRvIGRlY29kZSBhIGN1cnNvcj8gSSB0b2xkIHlvdSBpdCB3YXMgb3BhcXVlIDopCg==
        offset:
          type: integer
          minimum: 0
          description: Offset representing the current page
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            profile: access user profile information
            users:read: read-only access to registered users
            users:manage: read-write access to registered users
            roles: read-write access to user roles
            permissions: read-write access to user permissions