> ## 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. # Create a user > Creates an internal user in your organization with an organization role. The user has no app access until you assign an app. > [!WARNING] > > If you set `active` to `true`, KODE sends an email to the address you provide, with a link to set a password. Check the email address before you send the request. If you set `active` to `false`, the user is created disabled and no email is sent. > > To activate the user later, use [Update the status of a user](https://docs.kodelabs.com/products/kode-api/api-reference/users/update-the-status-of-a-user.md). > [!NOTE] > > The new user is always an `INTERNAL` user and has no app access. To give access, call [Assign an app to a user](https://docs.kodelabs.com/products/kode-api/api-reference/users/assign-an-app-to-a-user.md) with the `_id` from the response. > [!NOTE] > > The email address must be unique in your organization, and the API stores it in lower case. A second request with the same address, in any letter case, fails with `400`. Names can have up to 40 characters, and `position` up to 200. `phone` must be an international number that starts with `+`. Values that contain HTML tags are stored HTML-escaped. ## OpenAPI ````yaml /openapi/kode-api.yaml post /api/v1/users 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: post: tags: - Users summary: Create a user description: >- Creates an internal user in your organization with an organization role. The user has no app access until you assign an app. operationId: createUser requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' required: true responses: '200': description: The created user. The response is `200`, not `201`. content: application/json: schema: $ref: '#/components/schemas/UserPublic' '400': description: >- A required field is missing or too long, `email`, `phone`, or `role` is not valid, or a user with the same email already exists. `error.message` says which. A duplicate email returns "Invalid Email. Already in use!". '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: CreateUserRequest: type: object required: - firstName - lastName - email - role - active properties: firstName: type: string pattern: \S maxLength: 40 lastName: type: string pattern: \S maxLength: 40 email: type: string pattern: \S role: type: string pattern: \S active: type: boolean phone: type: string position: type: string maxLength: 200 UserPublic: type: object properties: _id: type: string organizationId: type: string createdAt: $ref: '#/components/schemas/Date' type: string readOnly: true updatedAt: $ref: '#/components/schemas/Date' type: string readOnly: true firstName: type: string lastName: type: string email: type: string phone: type: string position: type: string role: type: string memberType: type: string active: type: boolean invitationStatus: type: string assignedInApps: type: array items: $ref: '#/components/schemas/AppAssignmentPublic' Date: type: string description: >- Date and time in UTC, with a numeric offset and no colon, for example `2026-10-28T13:51:31+0000`. examples: - 2026-10-28T13:51:31+0000 AppAssignmentPublic: type: object properties: appId: type: string role: type: string assignmentStatus: type: string responses: Unauthorized: description: The access token is missing, invalid, or expired. Request a new token. Forbidden: description: The service account lacks permission for this building or operation. 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.