All Systems Operational
02 7250 7638
Docs/Account/API/Users

Users API

Manage users within a tenant — list, retrieve, update, delete, and manage role assignments. All endpoints require authentication and operate within the tenant context from the access token.

Base URL: https://id.vyntech.com.au/api/v1 — All endpoints on this page require a valid access token. The tenant is inferred from the tid claim in the JWT — you cannot access users from other tenants.

Returns the profile of the currently authenticated user. This is the most common endpoint for frontend apps to fetch user data after login.

Current UserAuth

Get the authenticated user's profile.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    User profile returned
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
Request
GET/api/v1/users/me
Response 200

Returns a paginated list of users within the tenant. Supports filtering by status, email search, and role. Requires users:read permission.

UsersAuth

List users in the current tenant with pagination and filtering.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    Users list returned
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:read permission

Query Parameters

  • Name
    page
    Type
    integer
    Description
    Page number for pagination
    Default: 1
  • Name
    per_page
    Type
    integer
    Description
    Results per page (max 100)
    Default: 20
  • Name
    status
    Type
    string
    Description
    Filter by status: active, suspended, or pending
  • Name
    search
    Type
    string
    Description
    Search by email or display_name (partial match)
  • Name
    role
    Type
    string
    Description
    Filter by role name (exact match)
  • Name
    sort
    Type
    string
    Description
    Sort field: created_at, email, last_login_at
    Default: created_at
  • Name
    order
    Type
    string
    Description
    Sort order: asc or desc
    Default: desc
Request
GET/api/v1/users
Response 200

Returns the full profile of a specific user by ID. Requires users:read permission.

UserAuth

Get a specific user by ID.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    User profile returned
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:read permission
  • Name
    404
    Type
    HTTP
    Description
    User not found in this tenant
Request
GET/api/v1/users/:id
Response 200

Updates a user's profile fields. Only provided fields are updated (partial update). Requires users:write permission, or the user can update their own profile without this permission.

UserAuth

Update a user's profile (partial update).

Payload Example

{
  "display_name": "Jane M. Smith",
  "status": "active"
}

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    User updated successfully
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:write permission (and not own profile)
  • Name
    404
    Type
    HTTP
    Description
    User not found in this tenant
  • Name
    422
    Type
    HTTP
    Description
    Invalid field value

Updatable Fields

  • Name
    display_name
    Type
    string
    Description
    User's display name (1-100 characters)
  • Name
    status
    Type
    string
    Description
    active or suspended — only admins with users:write can change this
Request
PATCH/api/v1/users/:id
Response 200

Permanently deletes a user and all associated data (sessions, role assignments, MFA config). This action is irreversible. Requires users:write permission.

UserAuth

Permanently delete a user and all their data.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    User deleted
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:write permission
  • Name
    404
    Type
    HTTP
    Description
    User not found in this tenant
Request
DELETE/api/v1/users/:id
Response 200

Returns all roles assigned to a specific user, including the permissions each role grants.

User RolesAuth

List all roles assigned to a user.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    User roles returned
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:read permission
  • Name
    404
    Type
    HTTP
    Description
    User not found
Request
GET/api/v1/users/:id/roles
Response 200

Assigns a role to a user. The role must exist within the tenant. If the user already has this role, the request is idempotent (returns 200 without error). Requires roles:manage permission.

Assign RoleAuth

Assign a role to a user.

Payload Example

{
  "role_id": "rol_01H8MNOP2Q4R6S8T"
}

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    Role assigned (or already assigned)
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing roles:manage permission
  • Name
    404
    Type
    HTTP
    Description
    User or role not found
Request
POST/api/v1/users/:id/roles
Response 200

Removes a role from a user. The user's effective permissions are recalculated immediately. Existing access tokens retain the old permissions until they expire. Requires roles:manage permission.

RoleAuth

Revoke a role from a user.

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    Role revoked
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing roles:manage permission
  • Name
    404
    Type
    HTTP
    Description
    User or role assignment not found
Request
DELETE/api/v1/users/:id/roles/:role_id
Response 200

Disables MFA for a user (admin action). Use this when a user has lost access to their authenticator app. The user will need to re-enroll MFA on their next login if the tenant enforces it. Requires users:write permission.

Reset User MFAAuth

Disable MFA for a user (admin action).

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    MFA reset successfully
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:write permission
  • Name
    404
    Type
    HTTP
    Description
    User not found
  • Name
    409
    Type
    HTTP
    Description
    User does not have MFA enabled
Request
POST/api/v1/users/:id/reset-mfa
Response 200

Triggers a new verification email for a user whose email is not yet verified (admin action). Useful when the original verification email was lost or expired. Requires users:write permission.

Resend User VerificationAuth

Send a new verification email to an unverified user (admin action).

Status Codes

  • Name
    200
    Type
    HTTP
    Description
    Verification email sent
  • Name
    401
    Type
    HTTP
    Description
    Invalid or expired access token
  • Name
    403
    Type
    HTTP
    Description
    Missing users:write permission
  • Name
    404
    Type
    HTTP
    Description
    User not found
  • Name
    409
    Type
    HTTP
    Description
    Email already verified
Request
POST/api/v1/users/:id/resend-verification
Response 200

What's Next

Sessions API →

List, revoke, and manage user sessions.

Roles & Permissions API →

Create roles, set permissions, and manage access control.

Authentication API →

Login, register, token refresh, and password flows.

Tenant Settings Guide →

Configure password policies, MFA enforcement, and session limits.

We use cookies and similar technologies to measure traffic and improve the site. You can choose which categories to allow. Manage Preferences.