> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set switchable values for a user or group

> <Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Replaces the values a user or group may switch this attribute to. Values are validated against the attribute type, such as `String`.

Provide one of `user_id` or `group_id`; providing both will result in an error.

<Warning>
  Provisioning a value grants data access. Shared extensions and access filters often route on the same attribute, so a switchable value typically lets the user read another tenant's rows. Provision only the values a user or group should see.
</Warning>


## Value requirements

* Values must be valid for the attribute's type; for example, a `Number` attribute rejects `acme`
* Requests can contain up to 300 values of up to 512 characters each. For a larger set, use `allow_any_value` instead.

## Removing provisioning

Sending `values: []` with `allow_any_value: false` removes the provisioning entirely. Any switch the user already made no longer applies and they fall back to their assigned value.


## OpenAPI

````yaml /api/openapi.yaml put /v1/user-attributes/{userAttributeId}/selectable-values
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: Who Am I
    description: Inspect your own user permissions
  - name: AI
    description: AI-powered query generation
  - name: AI Credit Controls
    description: Manage organization-level AI credit usage
  - name: AI Credit Usage
    description: Monitor AI credit usage
  - name: AI Evals
    description: >-
      Manage prompt sets and runs used to score AI quality against curated
      prompt suites.
  - name: AI Model Suggestions
    description: Manage AI-generated suggestions for shared models
  - name: AI Routines
    description: >-
      Manage Routines, which are scheduled, recurring AI-powered tasks that run
      automatically on your data
  - name: Apps
    description: Draft and publish app documents.
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish.
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Color Palettes
    description: Manage custom chart color palettes
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Embed
    description: Manage embed sessions
  - name: Labels
    description: |
      Manage labels in the organization
  - name: Folders
    description: Create and organize content folders
  - name: Folder labels
    description: Apply and manage labels on folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Skills
    description: >-
      Manage skills, the saved slash-command instructions the Omni AI assistant
      runs
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/user-attributes/{userAttributeId}/selectable-values:
    put:
      tags:
        - User attributes
      summary: Set switchable values for a user or group
      description: >
        <Note>
          **Organization Admin** permissions are required to use this endpoint.
        </Note>


        Replaces the values a user or group may switch this attribute to. Values
        are validated against the attribute type, such as `String`.


        Provide one of `user_id` or `group_id`; providing both will result in an
        error.


        <Warning>
          Provisioning a value grants data access. Shared extensions and access filters often route on the same attribute, so a switchable value typically lets the user read another tenant's rows. Provision only the values a user or group should see.
        </Warning>
      operationId: userAttributeSelectableValuesUpdate
      parameters:
        - $ref: '#/components/parameters/userAttributeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - type: object
                  title: For a user
                  required:
                    - user_id
                    - values
                  additionalProperties: false
                  properties:
                    user_id:
                      type: string
                      format: uuid
                      description: >-
                        The user's membership ID, not their user ID. Mutually
                        exclusive with `group_id`.
                      example: 8f14e45f-ceea-467a-9c2b-8f1d2a3b4c5d
                    values:
                      $ref: '#/components/schemas/UserAttributeSwitchValues'
                    allow_any_value:
                      $ref: '#/components/schemas/UserAttributeAllowAnyValue'
                      description: >
                        Whether the user can switch to a value that isn't
                        listed.
                - type: object
                  title: For a group
                  required:
                    - group_id
                    - values
                  additionalProperties: false
                  properties:
                    group_id:
                      type: string
                      format: uuid
                      description: The user group ID. Mutually exclusive with `user_id`.
                      example: 3c1a9b7e-2d4f-4a8b-9e0c-1f2a3b4c5d6e
                    values:
                      $ref: '#/components/schemas/UserAttributeSwitchValues'
                    allow_any_value:
                      $ref: '#/components/schemas/UserAttributeAllowAnyValue'
            examples:
              user:
                summary: Provision two values for a user
                value:
                  user_id: 8f14e45f-ceea-467a-9c2b-8f1d2a3b4c5d
                  values:
                    - acme
                    - globex
              groupAny:
                summary: Let a group switch to any value
                value:
                  group_id: 3c1a9b7e-2d4f-4a8b-9e0c-1f2a3b4c5d6e
                  values: []
                  allow_any_value: true
              revoke:
                summary: Remove a user's provisioning
                value:
                  user_id: 8f14e45f-ceea-467a-9c2b-8f1d2a3b4c5d
                  values: []
      responses:
        '200':
          description: The provisioning as stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectableValuesResponse'
              examples:
                user:
                  summary: Two values provisioned for a user
                  value:
                    user_attribute_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    values:
                      - acme
                      - globex
                    allow_any_value: false
                groupAny:
                  summary: Group allowed any value
                  value:
                    user_attribute_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    values: []
                    allow_any_value: true
        '400':
          description: >
            Bad Request. Both or neither of `user_id` and `group_id` were
            provided, the body failed validation, or a value is not valid for
            the attribute's type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
              examples:
                subject:
                  summary: Both subjects provided
                  value:
                    detail: Supply exactly one of user_id or group_id
                    status: 400
                type:
                  summary: Value rejected by the attribute type
                  value:
                    detail: >-
                      Invalid allowed values for "Region code": "acme" is not a
                      valid number
                    status: 400
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
              example:
                detail: 'Unauthorized: Missing or invalid API key'
                status: 401
        '403':
          description: |
            Forbidden. Requires Organization Admin permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
              example:
                detail: You do not have permission to manage user attributes
                status: 403
        '404':
          description: >
            Not Found. The user attribute definition, user, or group does not
            exist in the caller's organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
              example:
                detail: User attribute definition does not exist
                status: 404
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    userAttributeId:
      name: userAttributeId
      in: path
      required: true
      description: User attribute ID
      schema:
        type: string
        format: uuid
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  schemas:
    UserAttributeSwitchValues:
      type: array
      maxItems: 300
      items:
        type: string
        minLength: 1
        maxLength: 512
      description: >
        Values this user or group can switch the attribute to, validated against
        the attribute type. 


        Numbers are sent as strings to preserve precision beyond `2^53`. At most
        300 values of up to 512 characters each.
      example:
        - acme
        - globex
    UserAttributeAllowAnyValue:
      type: boolean
      description: >-
        Whether the user or group can switch to a value that is not listed. When
        `true`, `selectable_values` are suggestions.
      example: false
    SelectableValuesResponse:
      type: object
      required:
        - allow_any_value
        - user_attribute_id
        - values
      properties:
        user_attribute_id:
          $ref: '#/components/schemas/UserAttributeId'
          description: The user attribute definition this provisioning applies to.
        values:
          type: array
          maxItems: 300
          items:
            type: string
            minLength: 1
            maxLength: 512
          description: >
            Values this user or group can switch the attribute to. Numbers are
            returned as strings to preserve precision beyond `2^53`.
          example:
            - acme
            - globex
        allow_any_value:
          $ref: '#/components/schemas/UserAttributeAllowAnyValue'
    ApiError400:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 400
      required:
        - detail
        - status
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
        - detail
        - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
        - detail
        - status
    ApiError404:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 404
      required:
        - detail
        - status
    UserAttributeId:
      type: string
      description: >-
        Unique identifier for custom attributes. Empty string for system-defined
        attributes.
      example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    MethodNotAllowed:
      description: Method Not Allowed - Invalid HTTP method for this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#token-types).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.