openapi: 3.0.0
servers:
- description: Snowflake REST Server
  url: https://org-account.snowflakecomputing.com
info:
  version: 0.0.1
  title: Snowflake User API
  description: The Snowflake User API is a REST API that you can use to access, update,
    and perform certain action on Users in a Snowflake database.
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
paths:
  /api/v2/users:
    post:
      summary: Create a user
      tags:
      - user
      description: Create a user according to the parameters given
      operationId: createUser
      parameters:
      - $ref: common.yaml#/components/parameters/createMode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
    get:
      summary: List users in the system.
      tags:
      - user
      description: Lists the users in the system.
      operationId: listUsers
      parameters:
      - $ref: common.yaml#/components/parameters/like
      - $ref: common.yaml#/components/parameters/startsWith
      - $ref: common.yaml#/components/parameters/showLimit
      - $ref: common.yaml#/components/parameters/fromName
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
  /api/v2/users/{name}:
    get:
      parameters:
      - $ref: common.yaml#/components/parameters/name
      summary: Fetch information about a user
      tags:
      - user
      description: Fetch user information using the result of the DESCRIBE command
      operationId: fetchUser
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
    delete:
      parameters:
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/ifExists
      summary: Delete a user
      tags:
      - user
      description: Delete a user with the given name.
      operationId: deleteUser
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
    put:
      summary: Create a (or alter an existing) user.
      description: Create a (or alter an existing) user. Even if the operation is
        just an alter, the full property set must be provided. Note that password
        is not currently altered by this operation but is supported for a newly-created
        object.
      operationId: createOrAlterUser
      tags:
      - user
      parameters:
      - $ref: common.yaml#/components/parameters/name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
  /api/v2/users/{name}/grants:
    get:
      parameters:
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/showLimit
      summary: List all grants to the user
      tags:
      - user
      description: List all grants to the user
      operationId: listGrants
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Grant'
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
    post:
      summary: Grant a role to the user
      tags:
      - user
      description: Grant a role to the user
      operationId: grant
      parameters:
      - $ref: common.yaml#/components/parameters/name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Grant'
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
  /api/v2/users/{name}/grants:revoke:
    post:
      summary: Revoke grants from the user
      tags:
      - user
      description: Revoke grants from the user
      operationId: revokeGrants
      parameters:
      - $ref: common.yaml#/components/parameters/name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Grant'
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
  /api/v2/users/{name}:set-tags:
    post:
      summary: Set tags on a user.
      tags:
      - user
      description: Set tags on a user.
      operationId: setTags
      parameters:
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/ifExists
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: common.yaml#/components/schemas/TagAssignment
  /api/v2/users/{name}:unset-tags:
    post:
      summary: Unset tags from a user.
      tags:
      - user
      description: Unset tags from a user.
      operationId: unsetTags
      parameters:
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/ifExists
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: common.yaml#/components/schemas/TagReference
  /api/v2/users/{name}:get-tags:
    get:
      summary: Get the tag assignments for a user.
      tags:
      - user
      description: Returns all tags assigned to a user. This operation requires an
        active warehouse.
      operationId: getTags
      parameters:
      - $ref: common.yaml#/components/parameters/name
      - $ref: common.yaml#/components/parameters/withLineage
      responses:
        '200':
          description: successful
          headers:
            X-Snowflake-Request-ID:
              $ref: common.yaml#/components/headers/X-Snowflake-Request-ID
            Link:
              $ref: common.yaml#/components/headers/Link
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: common.yaml#/components/schemas/TagAssignment
        '202':
          $ref: common.yaml#/components/responses/202SuccessAcceptedResponse
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '408':
          $ref: common.yaml#/components/responses/408RequestTimeout
        '409':
          $ref: common.yaml#/components/responses/409Conflict
        '410':
          $ref: common.yaml#/components/responses/410Gone
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
components:
  schemas:
    Grant:
      type: object
      properties:
        securable:
          $ref: '#/components/schemas/Securable'
          description: Securable of the grant
        containing_scope:
          $ref: '#/components/schemas/ContainingScope'
          description: Containing scope of the grant
        securable_type:
          type: string
          description: Type of the securable to be granted. Only ROLE is supported
        privileges:
          type: array
          items:
            type: string
          description: List of privileges to be granted.
        created_on:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the grant was created
        granted_by:
          type: string
          readOnly: true
          description: The role that granted this privilege to this grantee
      required:
      - securable_type
    Securable:
      type: object
      properties:
        database:
          type: string
          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
          description: Database name of the securable if applicable.
        schema:
          type: string
          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
          description: Schema name of the securable if applicable.
        name:
          type: string
          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
          description: Name of the securable if applicable.
      required:
      - name
    ContainingScope:
      type: object
      properties:
        database:
          type: string
          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
          description: Database name of the securable scope if applicable.
        schema:
          type: string
          pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$
          description: Schema name of the securable scope if applicable.
      required:
      - database
    User:
      description: Properties of user.
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: User name
          example: jackpatel
        password:
          type: string
          format: password
          description: Password
        login_name:
          type: string
          description: Login name
        display_name:
          type: string
          description: Display name
        first_name:
          type: string
          description: First name
        middle_name:
          type: string
          description: Middle name
        last_name:
          type: string
          description: Last name
        email:
          type: string
          description: Email address
        must_change_password:
          type: boolean
          description: Does this user need to change their password (e.g., after assigning
            a temp password)
        disabled:
          type: boolean
          description: Has this user been disabled from the system
        days_to_expiry:
          type: integer
          description: How many days until this user expires
        mins_to_unlock:
          type: integer
          description: How many minutes until the account is unlocked after multiple
            failed logins
        default_warehouse:
          type: string
          description: The default warehouse to use when this user starts a session
        default_namespace:
          type: string
          description: The default namespace to use when this user starts a session
        default_role:
          type: string
          description: The default role to use when this user starts a session
        default_secondary_roles:
          type: string
          description: The default secondary roles of this user to use when starting
            a session. Only valid set values are ALL or NONE. Default is ALL after
            2024-07 BCR.
          enum:
          - ALL
          - NONE
          default: ALL
        mins_to_bypass_mfa:
          type: integer
          description: How many minutes until MFA is required again
        rsa_public_key:
          type: string
          description: RSA public key of the user
        rsa_public_key_2:
          type: string
          description: Second RSA public key of the user
        comment:
          type: string
          description: Comment about the user.
          example: A distinguished user
        type:
          type: string
          description: Indicates the type of user (PERSON | SERVICE | LEGACY_SERVICE)
        enable_unredacted_query_syntax_error:
          type: boolean
          description: Whether to show unredacted query syntax errors in the query
            history.
        network_policy:
          type: string
          description: Specifies an existing network policy is active for the user.
            Otherwise, use account default.
        created_on:
          type: string
          readOnly: true
          format: date-time
        last_successful_login:
          type: string
          readOnly: true
          format: date-time
        expires_at:
          type: string
          readOnly: true
          format: date-time
        locked_until:
          type: string
          readOnly: true
          format: date-time
        has_password:
          type: boolean
          readOnly: true
        has_rsa_public_key:
          type: boolean
          readOnly: true
        rsa_public_key_fp:
          type: string
          readOnly: true
          description: Fingerprint of the user's RSA public key
        rsa_public_key_2_fp:
          type: string
          readOnly: true
          description: Fingerprint of the user's second RSA public key
        ext_authn_duo:
          type: boolean
          readOnly: true
        ext_authn_uid:
          type: string
          readOnly: true
        owner:
          type: string
          readOnly: true
        snowflake_lock:
          type: boolean
          readOnly: true
          default: false
          description: Whether the user, account, or organization is locked by Snowflake.
        snowflake_support:
          type: boolean
          readOnly: true
          default: false
          description: Whether Snowflake Support is allowed to use the user or account
        mins_to_bypass_network_policy:
          type: integer
          readOnly: true
          description: Temporary bypass network policy on the user for a specified
            number of minutes
        password_last_set:
          type: string
          readOnly: true
          format: date-time
        custom_landing_page_url:
          type: string
          readOnly: true
        custom_landing_page_url_flush_next_ui_load:
          type: boolean
          readOnly: true
          default: false
          description: Whether or not to flush the custom landing page of the user
            on next UI load
  securitySchemes:
    KeyPair:
      $ref: common.yaml#/components/securitySchemes/KeyPair
    ExternalOAuth:
      $ref: common.yaml#/components/securitySchemes/ExternalOAuth
    SnowflakeOAuth:
      $ref: common.yaml#/components/securitySchemes/SnowflakeOAuth
    ProgrammaticAccessToken:
      $ref: common.yaml#/components/securitySchemes/ProgrammaticAccessToken
security:
- KeyPair: []
- ExternalOAuth: []
- SnowflakeOAuth: []
- ProgrammaticAccessToken: []