Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

The Users API is the entry point for provisioning human identities inside KaroKar. Every person who interacts with the platform — whether an internal employee, a fleet administrator, or a corporate contact — must first be registered as a User. User records are intentionally lightweight: they store only core identity fields and rely on the Organizations API membership model to grant roles and context. All endpoints sit behind the PermissionGuard; a valid Authorization bearer token is required on every call.

​
POST /users

Creates a new user account in the platform. Required permission: employee.manage
Only principals whose JWT contains the employee.manage permission may create users. Attempting this call with a token that lacks the permission returns 403 Forbidden.

​
Request body

​
firstName
string
required
The user’s given name. Must be a non-empty string.
​
lastName
string
required
The user’s family name. Must be a non-empty string.
​
email
string
required
A valid, unique email address. Validated with @IsEmail(). Duplicate email values will be rejected at the database level.
​
phone
string
Optional contact phone number. Any string format is accepted; normalisation is the caller’s responsibility.

​
Response

Returns the newly created User object.
​
id
string
UUID primary key, auto-generated.
​
firstName
string
The user’s given name.
​
lastName
string
The user’s family name.
​
email
string
Unique email address for this user.
​
phone
string | null
Contact phone number, or null if not provided.
​
createdAt
string (ISO 8601)
Timestamp of record creation, set automatically by the database.
​
updatedAt
string (ISO 8601)
Timestamp of the last update, maintained automatically by the database.

​
Example

curl -X POST http://localhost:3000/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Priya",
    "lastName": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+91-9876543210"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "priya.sharma@example.com",
  "phone": "+91-9876543210",
  "createdAt": "2024-06-01T10:00:00.000Z",
  "updatedAt": "2024-06-01T10:00:00.000Z"
}

​
Error cases

StatusReason
401 UnauthorizedMissing or expired Authorization bearer token.
403 ForbiddenAuthenticated principal lacks the employee.manage permission.
400 Bad RequestRequest body fails class-validator rules (e.g., email is not a valid address).

​
GET /users/:id

Retrieves a single user by their UUID. Required permission: None (authentication is still required via the PermissionGuard).
This endpoint returns null (with a 200 status) when no user matches the given ID. Consider checking for a null body before attempting to read user fields in your client code.

​
Path parameters

​
id
string
required
The UUID of the user to retrieve.

​
Response

Returns the matching User object, or null if no record exists for the provided ID.
​
id
string
UUID primary key of the user.
​
firstName
string
The user’s given name.
​
lastName
string
The user’s family name.
​
email
string
Unique email address for this user.
​
phone
string | null
Contact phone number, or null if not set.
​
createdAt
string (ISO 8601)
Timestamp of record creation.
​
updatedAt
string (ISO 8601)
Timestamp of the last update.

​
Example

curl http://localhost:3000/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "priya.sharma@example.com",
  "phone": "+91-9876543210",
  "createdAt": "2024-06-01T10:00:00.000Z",
  "updatedAt": "2024-06-01T10:00:00.000Z"
}

​
Error cases

StatusReason
401 UnauthorizedMissing or expired Authorization bearer token.

Build docs developers (and LLMs) love

Get started for freeTalk to us