Create User (Invite)

Create a new user and send them an invitation email. This endpoint enforces your organization's maximum user limit based on your subscription tier.

Request

POST https://api.entryguard.io/api/v1/users

Authentication

Requires a valid Bearer JWT token with ORG_ADMIN role.

Authorization: Bearer <access_token>

Request Body

{
  "email": "string",
  "name": "string",
  "isOrgAdmin": "boolean"
}

Field	Type	Required	Description
email	string	Yes	User's email address (must be valid email format and unique within the organization)
name	string	No	User's full name
isOrgAdmin	boolean	No	Whether to grant organization admin privileges (defaults to false)

Response

Returns the created user object.

Response Schema

{
  "id": "uuid",
  "email": "string",
  "name": "string",
  "isOrgAdmin": "boolean",
  "platformRole": "string",
  "isActive": "boolean",
  "mfaEnabled": "boolean",
  "lastLoginAt": "timestamp",
  "roleNames": ["string"],
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Success Response

Status Code: 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440006",
  "email": "[email protected]",
  "name": "New User",
  "isOrgAdmin": false,
  "platformRole": "CUSTOMER",
  "isActive": true,
  "mfaEnabled": false,
  "lastLoginAt": null,
  "roleNames": [],
  "createdAt": "2026-02-18T10:30:00Z",
  "updatedAt": "2026-02-18T10:30:00Z"
}

Error Responses

Status Code	Description
400 Bad Request	Invalid request body, invalid email format, duplicate email, or organization user limit reached
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	User does not have ORG_ADMIN role
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error occurred

Error Response Examples:

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "email is required",
  "path": "/api/v1/users"
}

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid email format",
  "path": "/api/v1/users"
}

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "A user with email '[email protected]' already exists",
  "path": "/api/v1/users"
}

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Organization has reached maximum user limit (5). Upgrade your plan to add more users.",
  "path": "/api/v1/users"
}

Example

Request

curl -X POST https://api.entryguard.io/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "New User",
    "isOrgAdmin": false
  }'

Response

{
  "id": "770e8400-e29b-41d4-a716-446655440006",
  "email": "[email protected]",
  "name": "New User",
  "isOrgAdmin": false,
  "platformRole": "CUSTOMER",
  "isActive": true,
  "mfaEnabled": false,
  "lastLoginAt": null,
  "roleNames": [],
  "createdAt": "2026-02-18T10:30:00Z",
  "updatedAt": "2026-02-18T10:30:00Z"
}

Notes

• An invitation email will be sent to the user's email address
• The user must complete registration by setting a password via the invitation link
• New users are created with isActive: true by default
• The maximum number of users depends on your organization's subscription tier:
  • Free: 1 user
  • Starter: 5 users
  • Business: 25 users
  • Enterprise: Unlimited users