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

# Assign an app to a user

> Gives a user access to an app with a role. The assignment finishes in the background.

> [!NOTE]
>
> Only `bms` can be assigned through the API. The value is case-sensitive. Any other `appId` fails with `400`, and so does a role that does not exist for your organization's `bms` app.

> [!NOTE]
>
> The response is `202` with no body, which means KODE accepted the assignment. It is not finished yet. Call [Get a user](https://docs.kodelabs.com/products/kode-api/api-reference/users/get-a-user.md) and read `assignedInApps[].assignmentStatus` until it is `SUCCEEDED` or `FAILED`. The values are `INITIALIZING`, `PROCESSING`, `SUCCEEDED`, `FAILED`, and `PENDING`. `PENDING` applies to a guest who has not accepted the invitation. The assignment does not run until the guest accepts.

> [!NOTE]
>
> `buildingIds` limits the user's access to those buildings. The IDs must be buildings of your organization. The API does not return them, so `assignedInApps` shows no building list.

> [!WARNING]
>
> Assigning an app to an active user can send that user an email. Check that the user is the right one before you send the request.


## OpenAPI

````yaml /openapi/kode-api.yaml post /api/v1/users/{userId}/apps/{appId}
openapi: 3.1.0
info:
  title: KODE API
  version: 1.0.0
  summary: Programmatic access to KODE OS resources and operations.
  description: >
    Use the KODE API to work with buildings, data sources, connectors, devices,
    points, virtual devices,

    timeseries data, schedules, the ontology, templating, mass writes, spaces,
    space assignments, tenants, meters, users, actions,

    and AssetOps work orders.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.kodelabs.com/kodeos
    description: KODE API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth 2.0 discovery, token, and revocation endpoints.
  - name: Buildings
    description: Buildings and their areas.
  - name: Data sources
    description: Data sources connected to a building.
  - name: Devices
    description: Devices and their points.
  - name: Points
    description: Point queries and point writes.
  - name: Timeseries
    description: Current and historical point values.
  - name: Actions
    description: Actions exposed by building data sources.
  - name: Work orders
    description: AssetOps work orders, lookups, comments, and attachments.
  - name: Connectors
    description: KODE API connectors and the devices and points ingested through them.
  - name: Schedules
    description: Schedules discovered on building data sources.
  - name: Templating
    description: Apply ontology templates to groups of points.
  - name: Virtual devices
    description: Virtual devices that group points from other devices.
  - name: Ontology
    description: Canonical types, fields, units, and connections of the KODE ontology.
  - name: Users
    description: Users of the organization and their app access.
  - name: Mass write
    description: Write values to many points across buildings, and follow each run.
  - name: Spaces
    description: Levels and space units of a building, and the meters located in them.
  - name: Space assignments
    description: Assign tenants to leasable spaces of a building for a period.
  - name: Tenants
    description: Tenants of a building, the people or companies that lease its spaces.
  - name: Meters
    description: >-
      Meters of a building, their space assignments, parent and child links, and
      readings.
paths:
  /api/v1/users/{userId}/apps/{appId}:
    post:
      tags:
        - Users
      summary: Assign an app to a user
      description: >-
        Gives a user access to an app with a role. The assignment finishes in
        the background.
      operationId: assignUserApp
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the app. Only `bms` is supported.
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the user.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignAppRequest'
        required: true
      responses:
        '202':
          description: >-
            KODE accepted the assignment. The response has no body. Read the
            user to follow the assignment.
        '400':
          description: >-
            The `appId` is not `bms`, `role` is missing or blank or not a role
            of your `bms` app, `buildingIds` is not a list or holds a building
            that does not exist, or the user already has the app ("App is
            already assigned").
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The service account is not allowed to assign this role.
        '404':
          description: No user with this `userId` exists in your organization.
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    AssignAppRequest:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          pattern: \S
        buildingIds:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: The access token is missing, invalid, or expired. Request a new token.
    TooManyRequests:
      description: >-
        A rate-limit window is exhausted. Wait, then retry with increasing
        delays.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Paste an access token from [Create an access
        token](/products/kode-api/api-reference/authentication/create-an-access-token).
        Tokens expire, so request a new one if you receive `401`.

````

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