Users

Planned feature: The endpoints described on this page are part of the planned API design and are not yet implemented in the current codebase.

The planned Users API will enable you to create and retrieve users within organizations. Users will be scoped to organizations and can have different roles and permissions across multiple organizations.

Authentication

All user endpoints require authentication using a JWT bearer token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get users

This endpoint returns users within the context of the authenticated user’s accessible organizations. Users can only see other users they have permission to view.

GET /api/users

Retrieves a list of users. You can filter by organization, role, status, and other criteria using query parameters.

Query parameters

organizationId

string

Filter users by organization ID (UUID)

page

integer

default:"1"

The page number for pagination

limit

integer

default:"20"

Number of users to return per page (maximum 100)

sort

string

default:"createdAt"

Field to sort by. Options: email, firstName, lastName, createdAt, updatedAt, lastLoginAt

order

string

default:"desc"

Sort order. Options: asc, desc

string

Search users by email, first name, or last name

role

string

Filter by role. Options: admin, member, viewer

status

string

Filter by user status. Options: active, pending, suspended, deleted

emailVerified

boolean

Filter by email verification status

Response

data

array

Array of user objects

Show User object

string

required

Unique identifier for the user (UUID)

string

required

User’s email address

firstName

string

User’s first name

lastName

string

User’s last name

displayName

string

User’s display name (auto-generated from first and last name if not provided)

avatarUrl

string

URL to the user’s avatar image

status

string

required

Current status of the user. Options: active, pending, suspended, deleted

emailVerified

boolean

required

Whether the user’s email has been verified

emailVerifiedAt

string

ISO 8601 timestamp when email was verified

ISO 8601 timestamp of the user’s last login

organizations

array

Array of organizations the user belongs to

Show Organization membership

organizationId

string

Organization ID (UUID)

organizationName

string

Organization name

role

string

User’s role in this organization. Options: owner, admin, member, viewer

joinedAt

string

ISO 8601 timestamp when the user joined this organization

preferences

object

User preferences and settings

Show Preferences object

timezone

string

User’s preferred timezone

language

string

User’s preferred language (ISO 639-1 code)

emailNotifications

boolean

Whether email notifications are enabled

metadata

object

Custom metadata key-value pairs

createdAt

string

required

ISO 8601 timestamp when the user was created

updatedAt

string

required

ISO 8601 timestamp when the user was last updated

pagination

object

Pagination metadata

Show Pagination object

Example request

curl -X GET "https://api.orgstack.io/api/users?organizationId=550e8400-e29b-41d4-a716-446655440000&status=active&page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Example response

200 - Success

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "email": "[email protected]",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "displayName": "Sarah Johnson",
      "avatarUrl": "https://cdn.orgstack.io/avatars/f47ac10b-58cc-4372-a567-0e02b2c3d479.jpg",
      "status": "active",
      "emailVerified": true,
      "emailVerifiedAt": "2024-01-16T09:30:00.000Z",
      "lastLoginAt": "2026-02-28T15:45:00.000Z",
      "organizations": [
        {
          "organizationId": "550e8400-e29b-41d4-a716-446655440000",
          "organizationName": "Acme Corporation",
          "role": "admin",
          "joinedAt": "2024-01-15T10:00:00.000Z"
        }
      ],
      "preferences": {
        "timezone": "America/New_York",
        "language": "en",
        "emailNotifications": true
      },
      "metadata": {
        "department": "Engineering",
        "employeeId": "ENG-001"
      },
      "createdAt": "2024-01-15T09:15:00.000Z",
      "updatedAt": "2026-02-25T11:20:00.000Z"
    },
    {
      "id": "3e4b9a87-c1d2-4f5e-9a8b-7c6d5e4f3a2b",
      "email": "[email protected]",
      "firstName": "Michael",
      "lastName": "Chen",
      "displayName": "Michael Chen",
      "avatarUrl": null,
      "status": "active",
      "emailVerified": true,
      "emailVerifiedAt": "2024-02-05T14:20:00.000Z",
      "lastLoginAt": "2026-02-27T09:15:00.000Z",
      "organizations": [
        {
          "organizationId": "550e8400-e29b-41d4-a716-446655440000",
          "organizationName": "Acme Corporation",
          "role": "member",
          "joinedAt": "2024-02-05T10:30:00.000Z"
        }
      ],
      "preferences": {
        "timezone": "America/Los_Angeles",
        "language": "en",
        "emailNotifications": false
      },
      "metadata": {
        "department": "Product",
        "employeeId": "PRD-042"
      },
      "createdAt": "2024-02-05T08:45:00.000Z",
      "updatedAt": "2026-01-10T16:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

401 - Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

403 - Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access users in this organization"
  }
}

Create user

Creating users requires appropriate permissions in the target organization. If email verification is required in the organization settings, the user will receive a verification email and their status will be pending until verified.

POST /api/users

Creates a new user and associates them with an organization. The user’s email must be unique across the platform.

Request body

string

required

User’s email address (must be a valid email format)

firstName

string

User’s first name (1-50 characters)

lastName

string

User’s last name (1-50 characters)

displayName

string

User’s display name (1-100 characters). If not provided, will be auto-generated from first and last name

password

string

required

User’s password (minimum 8 characters, must include uppercase, lowercase, number, and special character)

organizationId

string

required

ID of the organization to add the user to (UUID)

role

string

default:"member"

User’s role in the organization. Options: admin, member, viewer

sendInviteEmail

boolean

default:"true"

Whether to send an invitation email to the user

preferences

object

User preferences and settings

Show Preferences properties

preferences.timezone

string

default:"UTC"

User’s preferred timezone (IANA timezone identifier)

preferences.language

string

default:"en"

User’s preferred language (ISO 639-1 code)

preferences.emailNotifications

boolean

default:"true"

Enable email notifications

metadata

object

Custom metadata as key-value pairs (optional)

Response

Returns the created user object with all fields populated. Note that the password field is never returned in responses.

string

required

Unique identifier for the user (UUID)

string

required

User’s email address

firstName

string

User’s first name

lastName

string

User’s last name

displayName

string

User’s display name

status

string

required

User status (typically pending or active)

emailVerified

boolean

required

Email verification status (false for new users)

organizations

array

Array of organization memberships

preferences

object

User preferences

metadata

object

Custom metadata

createdAt

string

required

ISO 8601 timestamp when created

updatedAt

string

required

ISO 8601 timestamp when last updated

Example request

curl -X POST "https://api.orgstack.io/api/users" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Emma",
    "lastName": "Williams",
    "password": "SecureP@ssw0rd!",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "role": "member",
    "sendInviteEmail": true,
    "preferences": {
      "timezone": "Europe/London",
      "language": "en",
      "emailNotifications": true
    },
    "metadata": {
      "department": "Marketing",
      "startDate": "2026-03-15"
    }
  }'

Example response

201 - Created

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "email": "[email protected]",
  "firstName": "Emma",
  "lastName": "Williams",
  "displayName": "Emma Williams",
  "avatarUrl": null,
  "status": "pending",
  "emailVerified": false,
  "emailVerifiedAt": null,
  "lastLoginAt": null,
  "organizations": [
    {
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "organizationName": "Acme Corporation",
      "role": "member",
      "joinedAt": "2026-03-01T10:30:00.000Z"
    }
  ],
  "preferences": {
    "timezone": "Europe/London",
    "language": "en",
    "emailNotifications": true
  },
  "metadata": {
    "department": "Marketing",
    "startDate": "2026-03-15"
  },
  "createdAt": "2026-03-01T10:30:00.000Z",
  "updatedAt": "2026-03-01T10:30:00.000Z"
}

400 - Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters and include uppercase, lowercase, number, and special character"
      }
    ]
  }
}

401 - Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

403 - Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to create users in this organization"
  }
}

404 - Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

409 - Conflict

{
  "error": {
    "code": "CONFLICT",
    "message": "A user with this email already exists"
  }
}

Error codes

The Users API may return the following error codes:

Code	Description
`UNAUTHORIZED`	Missing or invalid authentication token
`FORBIDDEN`	Insufficient permissions to perform the action
`VALIDATION_ERROR`	Request body validation failed
`CONFLICT`	Resource conflict (e.g., duplicate email)
`NOT_FOUND`	User or organization not found
`RATE_LIMIT_EXCEEDED`	Too many requests, please retry later
`INTERNAL_ERROR`	Unexpected server error

Overview

Endpoints

Authentication

Get users

Query parameters

Response

Example request

Example response

Create user

Request body

Response

Example request

Example response

Error codes

Build docs developers (and LLMs) love

Overview

Endpoints

​Authentication

​Get users

​Query parameters

​Response

​Example request

​Example response

​Create user

​Request body

​Response

​Example request

​Example response

​Error codes

Build docs developers (and LLMs) love

Authentication

Get users

Query parameters

Response

Example request

Example response

Create user

Request body

Response

Example request

Example response

Error codes