---
title: "Create a user"
method: POST
path: "/users"
tags: ["Users"]
---

# Create a user

`POST /users`

Adds a new user to the account. The user may be configured as an admin or standard user, and (if a standard user) may be assigned a restricted [home directory](/docs/account/04-users/00-introduction#setting-the-user-s-home-directory) and restricted [permissions](/docs/account/04-users/00-introduction#managing-user-roles-and-permissions). 

**Notes:**

- You must be an [admin-level user](/docs/account/04-users/00-introduction#managing-user-roles-and-permissions) to use this.

## Headers

- `ev-api-key` string, required
- `ev-access-token` string, required

## Request body

- object
  - `username` string, required — Username of the user to create. This should follow standard username conventions - spaces are not allowed, etc. We do allow email addresses as usernames. **Note** Usernames must be unique across all ExaVault accounts.
  - `nickname` string — An optional nickname (e.g. 'David from Sales').
  - `homeResource` string, required — Resource identifier for the user's home folder. See details on [how to specify resources](#section/Identifying-Resources) above. The user will be locked to this directory and unable to move 'up' in the account. If the folder does not exist in the account, it will be created when the user is created. Users with the `role` **admin** should have their homeResource set to '/'
  - `email` string, email, required — Email address for the user
  - `password` string, required — Password for the user
  - `role` 'user' | 'admin', required — The type of user to create, either **user** or **admin**.
  - `permissions` object, required — An object containing name/value pairs for each permission. Any permission that is not passed will be set to `false` by default. Note that users will be unable to see any files in the account unless you include `list` permission. When creating a user with the `role` **admin**, you should set all of the permissions to `true`
    - `list` boolean
    - `download` boolean
    - `upload` boolean
    - `modify` boolean
    - `delete` boolean
    - `changePassword` boolean
    - `share` boolean
    - `notification` boolean
    - `viewFormData` boolean
    - `deleteFormData` boolean
  - `timeZone` string, required — Time zone, used for accurate time display within the application. See <a href='https://php.net/manual/en/timezones.php' target='blank'>this page</a> for allowed values.
  - `expiration` string — Optional timestamp when the user should expire, formatted in date-time.
  - `locked` boolean — If true, the user will not be able to log in
  - `welcomeEmail` boolean — If **true**, send this new user a welcome email upon creation. The content of the welcome email can be configured with the [PATCH /accounts](#operation/updateAccount) method.
  - `onboarding` boolean — Set this to **true** to enable extra help popups in the web file manager for this user.

## Response `201`

Successful Operation

- UserResponse — Response object for users.
  - `responseStatus` integer — Http code for the response.
  - `data` User — Object contains user properties.
    - `id` integer — ID of the user.
    - `type` string — Type of object being returned. Always "user"
    - `attributes` UserAttributes — Attributes of the user including expiration, home directory, and permissions.
      - `status` 0 | 1, required — Indicates user activity status. `0` means the user is locked and cannot log in. `1` means the user is active and can log in.
      - `locked` boolean — `true` if the user is locked and cannot log in.
      - `expiration` string — Timestamp of user expiration.
      - `created` string, date-time, required — Timestamp of user creation.
      - `modified` string, date-time, required — Timestamp of user modification.
      - `accessTimestamp` string — Timestamp of most recent successful user login.
      - `accountName` string, required — Name of the account this user belongs to.
      - `username` string, required — Username of the user.
      - `nickname` string, required — Nickname of the user.
      - `email` string — Email address of the user.
      - `homePath` string — Path to the user's home folder.
      - `permissions` UserPermissions, required
        - `download` boolean, required — Download permission flag
        - `upload` boolean, required — Upload permission flag
        - `modify` boolean, required — Modify permission flag
        - `delete` boolean, required — Delete permission flag
        - `list` boolean, required — View folder contents permission flag
        - `changePassword` boolean, required — Change (own) password permission flag
        - `share` boolean, required — Sharing permission flag
        - `notification` boolean, required — Notifications permission flag
        - `viewFormData` boolean, required — Access Form Data permission flag. If true, user can view submissions that have been stored for a receive folder. This includes any data submitted in the receive folder form.
        - `deleteFormData` boolean, required — Delete form data permission flag. If true, user can remove data that was submitted for a receive folder. This applies only to data submitted in the receive folder form, not the actual files uploaded.
      - `role` 'user' | 'admin' | 'master', required — User's access level
      - `timeZone` string, required — User's timezone. See <a href='https://php.net/manual/en/timezones.php' target='blank'>this page</a> for allowed values.
      - `onboarding` boolean, required — Whether the onboarding help system is enabled for this user. `true` means that additional help popups are displayed in the web application for this user.
      - `firstLogin` boolean — `true` if the user has logged into the system.
    - `relationships` object — Home resource and owner account relationship data for the user.
      - `homeResource` object
        - `data` object
          - `type` 'resource' — Type is resource.
          - `id` integer — ID of home directory resource.
      - `ownerAccount` object, required
        - `data` object
          - `type` 'account' — Type is account.
          - `id` integer — ID of the account.
  - `included` union[]
    - union
      - Account — Object contains all account properties.
        - `id` integer — Account ID
        - `type` 'account' — Type of item. "account"
        - `attributes` AccountAttributes — unresolved $ref
        - `relationships` object
          - `masterUser` object
            - `data` object
              - …
      - Resource — All properties of the resource.
        - `id` integer
        - `type` 'resource' — Type of item. "resource"
        - `attributes` ResourceAttributes — Attributes of resource
          - `hash` string — Unique hash of the resource.
          - `name` string — Resource name, e.g. the name of the file or folder.
          - `extension` string — Resource extension. Property exists only if resource `type` is file.
          - `type` 'file' | 'dir' — Type of the resource.
          - `createdBy` string — Username of the creator.
          - `uploadDate` string, date-time — Timestamp of resource upload.
          - `createdAt` string, date-time — Date-time of resource creation.
          - `updatedAt` string, date-time — Date-time of resource modification.
          - `accessedAt` string, date-time — Date-time of the time when resource was accessed.
          - `createdTime` integer — UNIX timestamp of resource creation
          - `updatedTime` integer — UNIX timestamp of resource modification
          - `accessedTime` integer — UNIX timestamp of last access
          - `path` string — Full path to the resource.
          - `size` integer — Resource size in bytes
          - `fileCount` integer — Number of files within folder. null if resource type is a file.
          - `previewable` true | false — Can resource be previewed. Property equals `null` if resource `type` is dir.
        - `relationships` object
          - `share` object
            - `data` object
              - …
          - `notifications` object[]
            - `data` object
              - …
          - `directFile` object
            - `data` object
              - …
          - `parentResource` object
            - `data` object
              - …

---

[API](https://skmtc.net/prismic/apis/exavault-api.md) · [All operations](https://skmtc.net/prismic/apis/exavault-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prismic/exavault-api/revisions/a1bd874b5960/schema)