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

# Create a user

`POST /v2/users`

Creates a user in the current customer account. Use this endpoint to add users programmatically, assign roles, and set up access permissions.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateUserRequest — Request to create a new user account in the platform.
  - `email` string, email, required — The email address for the user.
  - `username` string — The username for the user. The value defaults to the email.
  - `description` string — The description of the user.
  - `api_roles` ApiRole[] — The customer-level role names assigned to the user.
  - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for the user.
    - `corpus_key` string, required — The key of the corpus this role applies to.
    - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus.
  - `agent_roles` AgentRole[] — Agent-specific role assignments for the user.
    - `agent_key` string, required — The key of the agent this role applies to.
    - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies. This must be the only role the user holds. The platform rejects assigning it alongside any other role.

## Response `201`

The response returns a `user` object that contains the assigned user ID, email, username, enabled status, description, creation timestamp, and assigned API roles.

- object — A user account with associated profile information and permissions.
  - `id` string, required — The Vectara ID for the user.
  - `email` string, email, required — The email address for the user.
  - `username` string — The username for the user.
  - `enabled` boolean — Indicates whether the user is enabled or disabled.
  - `description` string — The description of the user.
  - `created_at` string, date-time — When the user was created.
  - `updated_at` string, date-time — When a user property was last updated.
  - `api_roles` ApiRole[] — The customer-level role names of the user.
  - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for the user.
    - `corpus_key` string, required — The key of the corpus this role applies to.
    - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus.
  - `agent_roles` AgentRole[] — Agent-specific role assignments for the user.
    - `agent_key` string, required — The key of the agent this role applies to.
    - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies. This must be the only role the user holds. The platform rejects assigning it alongside any other role.
  - `api_policy` ApiPolicy — The actions a principal can take on the Vectara platform.
    - `name` string, required — The name of the API role.
    - `allowed_operations` object, required — The operations the API role allows. Each operation may allow only certain resources, described by a map of resource path to resource values. If the value is null, the operation allows any resource.
  - `one_time_code` string — A one-time code the new user uses to create a password. This is optional, and is only populated for some platform deployments.
  - `one_time_code_link` string — The link where the user enters the `one_time_code`. This is optional, and is only populated for some platform deployments.

## Other responses

- `400` — User creation request was malformed.
- `403` — Permissions do not allow creating a user.

---

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