Users

The /users endpoint allows you to retrieve, update, and delete user profiles. Access is scoped to users within your account — users outside your account are not visible.

Authorization Rules

• Self-access: Any authenticated user can read and update their own profile.
• Same-account access: Any account member can read other users in the same account.
• Admin-only writes: Only account admins can update or delete other users' profiles.
• Protected fields: The email, externalId, and source fields cannot be modified through this API. They are managed by the signup and SCIM sync processes.

Retrieve User

Retrieve a user profile by ID. The target user must be a member of your current account.

Endpoint: /users/<USER_ID>

Method: GET

Requirements: User must have account:member permission. Target user must be in the same account.

Headers

Path Parameters

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<USER_ID>",
    "externalId": "<EXTERNAL_ID>",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "johndoe",
    "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
    "language": "en",
    "phone": "+15555551212",
    "sign_in_provider": "google.com",
    "last_selected_account": "<ACCOUNT_ID>",
    "source": "firebase",
    "updated_by": "user:<USER_ID>",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-06-20T14:45:00.000Z"
}

Code Example

curl --location --request GET 'https://api.vertesia.io/api/v1/users/<USER_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Error Responses

Update User

Update a user profile. Users can update their own profile. Account admins can update any user in the same account.

Only the following fields can be modified: name, username, picture, language, phone, last_selected_account. Any other fields in the payload are silently ignored.

Endpoint: /users/<USER_ID>

Method: PUT

Requirements: User must have account:member permission for self-update, or account:admin permission to update another user. Target user must be in the same account.

Headers

Path Parameters

Input Parameters

Example Request

{
    "name": "John D.",
    "language": "fr",
    "phone": "+33612345678"
}

Example Response

{
    "id": "<USER_ID>",
    "externalId": "<EXTERNAL_ID>",
    "email": "john.doe@example.com",
    "name": "John D.",
    "username": "johndoe",
    "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
    "language": "fr",
    "phone": "+33612345678",
    "sign_in_provider": "google.com",
    "last_selected_account": "<ACCOUNT_ID>",
    "source": "firebase",
    "updated_by": "user:<USER_ID>",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-06-20T15:00:00.000Z"
}

Code Example

curl --location --request PUT 'https://api.vertesia.io/api/v1/users/<USER_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "John D.",
    "language": "fr",
    "phone": "+33612345678"
}'

Error Responses

Delete User

Delete a user from the system. Only account admins can delete users, and only users within the same account. Self-deletion is not allowed.

Endpoint: /users/<USER_ID>

Method: DELETE

Requirements: User must have account:admin permission. Target user must be in the same account. Self-deletion is not permitted.

Headers

Path Parameters

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<USER_ID>"
}

Code Example

curl --location --request DELETE 'https://api.vertesia.io/api/v1/users/<USER_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Error Responses