Sync a user with the Node.js SDK
permit.api.users.sync() creates a user in the Permit.io environment that your Node.js SDK client is connected to, or updates the user if the key already exists. Call the method from your backend when a user signs up or signs in, so that permit.check() can evaluate checks for that user. This reference is for backend developers who connect their authentication flow to Permit. For the full sync workflow, see Sync users.
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.sync | sync(userData: UserCreate): Promise<{ user: UserRead; created: boolean }> | Recommended |
permit.api.syncUser | syncUser(user: UserCreate): Promise<UserRead> | Deprecated alias. Resolves to the user object only. |
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 { user: syncedUser, created } = await permit.api.users.sync(user);
Return value
permit.api.users.sync() resolves to an object with two fields:
| Field | Type | Description |
|---|---|---|
user | UserRead | The created or updated user, with key, id, email, first_name, last_name, attributes, roles, associated_tenants, created_at, and updated_at. |
created | boolean | true if the Permit API created the user (status code 201). false if the API updated an existing user (status code 200). |
The deprecated permit.api.syncUser() resolves to the UserRead object only.
If the Permit API returns an error status code, permit.api.users.sync() throws a PermitApiError. The deprecated permit.api.syncUser() rethrows the underlying Axios error.
Change roles after the first sync
Use permit.api.users.sync() to create the user and keep profile fields and attributes current. To change the roles of a user who already exists in Permit, call permit.api.users.assignRole() and permit.api.users.unassignRole().