Create a user with the Node.js SDK
permit.api.users.create() creates a user in the Permit.io environment that your Node.js SDK client is connected to. After Permit has the user, permit.check() can evaluate permission checks for that user. This reference is for backend developers who add users to Permit from code.
permit.api.users.create() fails if a user with the same key exists. To create a user or update an existing one in a single call, use Sync a user with the Node.js SDK.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client and Get your API key.
Method signature
| Method | Signature | Status |
|---|---|---|
permit.api.users.create | create(userData: UserCreate): Promise<UserRead> | Recommended |
permit.api.createUser | createUser(user: UserCreate): Promise<UserRead> | Deprecated alias with the same argument |
Parameters
The method takes one argument: a UserCreate object.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Unique identifier of the user in the environment. Pass the same key to permit.check(). Use any value that is unique in your system and URL-friendly, such as the user ID from your identity provider. |
email | string | No | Email of the user. Unique in the environment. |
first_name | string | No | First name of the user. |
last_name | string | No | Last name of the user. |
attributes | object | No | User attributes that attribute-based access control (ABAC) policies can evaluate. |
role_assignments | UserRoleCreate[] | No | Roles to assign to the user. Each item has a role key and optionally a tenant key. |
Example UserCreate object. Replace the placeholder values with the data of your user.
{
key: "key",
email: "email@example.com",
first_name: "John",
last_name: "Smith",
attributes: {}
}
Example
const response = await permit.api.users.create(user);
Return value
The method resolves to a UserRead object: the fields you sent, plus id, organization_id, project_id, environment_id, created_at, updated_at, roles, and associated_tenants.
If a user with the same key exists, the Permit API returns status code 409. permit.api.users.create() throws a PermitApiError for 409 and for any other error status code. The deprecated permit.api.createUser() rethrows the underlying Axios error.