Sync a user with the Ruby SDK
permit.sync_user() creates a user in the Permit.io environment that your API key belongs 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 Ruby backend developers who connect their authentication flow to Permit. For the full sync workflow, see Sync users.
Prerequisites
- A
permitclient created withPermit.newand an API key for the environment. See Check permissions with the Ruby SDK and Get your API key.
Method signature
| Method | Signature |
|---|---|
permit.sync_user | sync_user(user) |
permit.api.users.sync_user | sync_user(user). permit.sync_user calls this method. |
Parameters
user is a Hash with symbol keys, or an OpenapiClient::UserCreate object. A String raises a KeyError.
User hash fields
| Key | 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 (slugified), 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 | Hash | No | User attributes that attribute-based access control (ABAC) policies can evaluate. |
Example user hash. Replace the placeholder values with the data of your user.
user = {"key": "user-key", "email": "john@doe.com", "first_name": "John", "last_name": "Doe", "attributes": {"age": "26"}}
Example
new_user = permit.sync_user(user)
Return value
permit.sync_user() fetches the user by key first:
| Result of the fetch | What sync_user does | Return value |
|---|---|---|
| Status code 404 | Creates the user with the hash fields. | The created user as an OpenapiClient::UserRead object. |
| User found | Updates the user with the hash fields other than key. | The updated user as an OpenapiClient::UserRead object. |
| Any other error | Raises the OpenapiClient::ApiError. | None |
sync_user removes key from the Hash you pass. If the user exists and the hash has no fields other than key, sync_user raises an error with the message empty user object, nothing to update. A hash without key raises a KeyError.
Change roles after the first sync
Use sync_user to create the user and keep profile fields and attributes current. The Ruby SDK has no role assignment method. To change the roles of a user who exists in Permit, call the assign role API endpoint and the unassign role API endpoint, or use the Permit dashboard.