openapi: 3.0.3
info:
  title: Weaviate REST authz users API
  description: '# Introduction<br/> Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. <br/> ### Base Path <br/>The base path for the Weaviate server is structured as `[YOUR-WEAVIATE-HOST]:[PORT]/v1`. As an example, if you wish to access the `schema` endpoint on a local instance, you would navigate to `http://localhost:8080/v1/schema`. Ensure you replace `[YOUR-WEAVIATE-HOST]` and `[PORT]` with your actual server host and port number respectively. <br/> ### Questions? <br/>If you have any comments or questions, please feel free to reach out to us at the community forum [https://forum.weaviate.io/](https://forum.weaviate.io/). <br/>### Issues? <br/>If you find a bug or want to file a feature request, please open an issue on our GitHub repository for [Weaviate](https://github.com/weaviate/weaviate). <br/>### Need more documentation? <br/>For a quickstart, code examples, concepts and more, please visit our [documentation page](https://docs.weaviate.io/weaviate).'
  version: 1.38.0-dev
servers:
- url: http://localhost:8080
  description: Local Weaviate instance
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: users
paths:
  /users/own-info:
    get:
      summary: Weaviate Get Current User Info
      description: Get information about the currently authenticated user, including username and assigned roles.
      tags:
      - users
      operationId: getOwnInfo
      responses:
        '200':
          description: Info about the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOwnInfo'
        '401':
          description: Unauthorized or invalid credentials.
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: Replica movement operations are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /users/db:
    get:
      summary: Weaviate List All Users
      description: Retrieves a list of all database (`db` user type) users with their roles and status information.
      tags:
      - users
      operationId: listAllUsers
      parameters:
      - name: includeLastUsedTime
        in: query
        required: false
        description: Whether to include the last time the users were utilized.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Info about the users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DBUserInfo'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /users/db/{user_id}:
    get:
      summary: Weaviate Get User Info
      description: Retrieve detailed information about a specific database user (`db` user type), including their roles, status, and type.
      tags:
      - users
      operationId: getUserInfo
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      - name: includeLastUsedTime
        in: query
        required: false
        description: Whether to include the last used time of the given user
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Info about the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DBUserInfo'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    post:
      summary: Weaviate Create A New User
      description: Create a new database (`db` user type) user with the specified name. Returns an API key for the newly created user.
      tags:
      - users
      operationId: createUser
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                import:
                  type: boolean
                  description: EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN. - import api key from static user
                  default: false
                createTime:
                  type: string
                  format: date-time
                  description: EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN. - set the given time as creation time
                namespace:
                  type: string
                  description: Namespace to bind the new user to. Required on namespace-enabled clusters. Must be set by a global operator only.
      responses:
        '201':
          description: User created successfully and API key returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApiKey'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A user with the specified name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    delete:
      summary: Weaviate Delete A User
      description: Delete a database user. You can't delete your current user.
      tags:
      - users
      operationId: deleteUser
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted.
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /users/db/{user_id}/rotate-key:
    post:
      summary: Weaviate Rotate API Key Of A User
      description: Revoke the current API key for the specified database user (`db` user type) and generate a new one.
      tags:
      - users
      operationId: rotateUserApiKey
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      responses:
        '200':
          description: API key successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApiKey'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /users/db/{user_id}/activate:
    post:
      summary: Weaviate Activate A User
      description: Activate a deactivated database user (`db` user type).
      tags:
      - users
      operationId: activateUser
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      responses:
        '200':
          description: User successfully activated.
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '409':
          description: User already activated.
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /users/db/{user_id}/deactivate:
    post:
      summary: Weaviate Deactivate A User
      description: Deactivate a database user (`db` user type).
      tags:
      - users
      operationId: deactivateUser
      parameters:
      - name: user_id
        in: path
        required: true
        description: The name of the user.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                revoke_key:
                  type: boolean
                  description: Whether the API key should be revoked when deactivating the user.
                  default: false
      responses:
        '200':
          description: User successfully deactivated.
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '409':
          description: User already deactivated.
        '422':
          description: The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
components:
  schemas:
    Role:
      type: object
      required:
      - name
      - permissions
      properties:
        name:
          type: string
          description: The name (ID) of the role.
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    UserApiKey:
      type: object
      required:
      - apikey
      properties:
        apikey:
          type: string
          description: The API key associated with the user.
    DBUserInfo:
      type: object
      required:
      - userId
      - dbUserType
      - roles
      - active
      properties:
        roles:
          type: array
          description: The roles associated with the user.
          items:
            type: string
        userId:
          type: string
          description: The name (ID) of the user.
        dbUserType:
          type: string
          description: Type of the returned user.
          enum:
          - db_user
          - db_env_user
        active:
          type: boolean
          description: Activity status of the returned user.
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
          description: 'Date and time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
        apiKeyFirstLetters:
          type:
          - string
          - 'null'
          description: First 3 letters of the associated API key.
          maxLength: 3
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: 'Date and time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.'
        namespace:
          type: string
          description: The namespace this user is bound to. Only populated for callers with global-operator privileges; omitted otherwise.
    Permission:
      type: object
      description: Permissions attached to a role.
      required:
      - action
      properties:
        backups:
          type: object
          description: Resources applicable for backup actions.
          properties:
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
        data:
          type: object
          description: Resources applicable for data actions.
          properties:
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
            tenant:
              type: string
              description: A string that specifies which tenants this permission applies to. Can be an exact tenant name or a regex pattern. The default value `*` applies the permission to all tenants.
              default: '*'
            object:
              type: string
              description: A string that specifies which objects this permission applies to. Can be an exact object ID or a regex pattern. The default value `*` applies the permission to all objects.
              default: '*'
        nodes:
          type: object
          description: Resources applicable for cluster actions.
          properties:
            verbosity:
              type: string
              description: Whether to allow (verbose) returning shards and stats data in the response.
              enum:
              - verbose
              - minimal
              default: minimal
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
        users:
          type: object
          description: Resources applicable for user actions.
          properties:
            users:
              type: string
              description: A string that specifies which users this permission applies to. Can be an exact user name or a regex pattern. The default value `*` applies the permission to all users.
              default: '*'
        groups:
          type: object
          description: Resources applicable for group actions.
          properties:
            group:
              type: string
              description: A string that specifies which groups this permission applies to. Can be an exact group name or a regex pattern. The default value `*` applies the permission to all groups.
              default: '*'
            groupType:
              $ref: '#/components/schemas/GroupType'
        tenants:
          type: object
          description: Resources applicable for tenant actions.
          properties:
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
            tenant:
              type: string
              description: A string that specifies which tenants this permission applies to. Can be an exact tenant name or a regex pattern. The default value `*` applies the permission to all tenants.
              default: '*'
        roles:
          type: object
          description: Resources applicable for role actions.
          properties:
            role:
              type: string
              description: A string that specifies which roles this permission applies to. Can be an exact role name or a regex pattern. The default value `*` applies the permission to all roles.
              default: '*'
            scope:
              type: string
              description: Set the scope for the manage role permission.
              enum:
              - all
              - match
              default: match
        collections:
          type: object
          description: Resources applicable for collection and/or tenant actions.
          properties:
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
        replicate:
          type: object
          description: resources applicable for replicate actions
          properties:
            collection:
              type: string
              description: string or regex. if a specific collection name, if left empty it will be ALL or *
              default: '*'
            shard:
              type: string
              description: string or regex. if a specific shard name, if left empty it will be ALL or *
              default: '*'
        aliases:
          type: object
          description: Resource definition for alias-related actions and permissions. Used to specify which aliases and collections can be accessed or modified.
          properties:
            collection:
              type: string
              description: A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections.
              default: '*'
            alias:
              type: string
              description: A string that specifies which aliases this permission applies to. Can be an exact alias name or a regex pattern. The default value `*` applies the permission to all aliases.
              default: '*'
        namespaces:
          type: object
          description: Resources applicable for namespace actions.
          properties:
            namespace:
              type: string
              description: A string that specifies which namespaces this permission applies to. Can be an exact namespace name or a regex pattern. The default value `*` applies the permission to all namespaces.
              default: '*'
        action:
          type: string
          description: Allowed actions in weaviate.
          enum:
          - manage_backups
          - read_cluster
          - create_data
          - read_data
          - update_data
          - delete_data
          - read_nodes
          - create_roles
          - read_roles
          - update_roles
          - delete_roles
          - create_collections
          - read_collections
          - update_collections
          - delete_collections
          - assign_and_revoke_users
          - create_users
          - read_users
          - update_users
          - delete_users
          - create_tenants
          - read_tenants
          - update_tenants
          - delete_tenants
          - create_replicate
          - read_replicate
          - update_replicate
          - delete_replicate
          - create_aliases
          - read_aliases
          - update_aliases
          - delete_aliases
          - assign_and_revoke_groups
          - read_groups
          - create_mcp
          - read_mcp
          - update_mcp
          - manage_namespaces
    GroupType:
      type: string
      description: If the group contains OIDC or database users.
      enum:
      - oidc
    ErrorResponse:
      type: object
      description: An error response returned by Weaviate endpoints.
      properties:
        error:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
    UserOwnInfo:
      type: object
      required:
      - username
      properties:
        groups:
          type: array
          description: The groups associated with the user.
          items:
            type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        username:
          type: string
          description: The name (ID) of the user.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OIDC/JWT bearer authentication