---
title: "Create User"
method: POST
path: "/v2/facts/{proj_id}/{env_id}/users"
tags: ["Users"]
---

# Create User

`POST /v2/facts/{proj_id}/{env_id}/users`

Creates a new user inside the Permit.io system, from that point forward
you may run permission checks on that user.

Returns 201 if the user is created, 409 if the user already exists.
User is identified by its key, and you can only create one user with the same key inside a Permit environment.

## Path parameters

- `proj_id` string, required — Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").
- `env_id` string, required — Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").

## Request body

- UserCreate
  - `key` string, required — A unique id by which Permit will identify the user for permission checks.
  - `email` string, email — The email of the user. If synced, will be unique inside the environment.
  - `first_name` string — First name of the user.
  - `last_name` string — Last name of the user.
  - `attributes` object — Arbitrary user attributes that will be used to enforce attribute-based access control policies.
  - `role_assignments` UserRoleCreate[] — List of roles to assign to the user in the environment.
    - `role` string, required — the role that will be assigned (accepts either the role id or the role key)
    - `tenant` string — the tenant the role is associated with (accepts either the tenant id or the tenant key)
    - `resource_instance` string — the resource instance the role is associated with (accepts either the resource instance id or key using this format resource_type:resource_instance)The resource instance will be implicitly created if the tenant parameter is specified and the resource instance does not exist.

## Response `200`

Successful Response

- UserRead
  - `key` string, required — A unique id by which Permit will identify the user for permission checks.
  - `id` string, uuid, required — Unique id of the user
  - `organization_id` string, uuid, required — Unique id of the organization that the user belongs to.
  - `project_id` string, uuid, required — Unique id of the project that the user belongs to.
  - `environment_id` string, uuid, required — Unique id of the environment that the user belongs to.
  - `associated_tenants` UserInTenant[]
    - `tenant` string, required — The tenant key which the user is associated with
    - `roles` string[], required — List of roles assigned to the user in that tenant
    - `status` 'active' | 'pending', required — An enumeration.
    - `resource_instance_roles` UserResourceInstanceRole[]
      - `resource_instance` string, required — The resource instance key which the role is associated with
      - `resource` string, required — The resource type which the role is associated with
      - `role` string, required — The role key of this resource role
  - `roles` UserRole[]
    - `role` string, required — the role that is assigned
    - `tenant` string, required — the tenant the role is associated with
  - `created_at` string, date-time, required — Date and time when the user was created (ISO_8601 format).
  - `updated_at` string, date-time, required — Date and time when the user was last updated/modified (ISO_8601 format).
  - `email` string, email — The email of the user. If synced, will be unique inside the environment.
  - `first_name` string — First name of the user.
  - `last_name` string — Last name of the user.
  - `attributes` object — Arbitrary user attributes that will be used to enforce attribute-based access control policies.

## Other responses

- `422` — Validation Error

---

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