REST Endpoints

List Users

GET/api/v1/users

Retrieves a paginated list of users from your organization.

Query Parameters

Name	Type	Description
`page`	integer	Page number (starts at 1)
`limit`	integer	Number of results per page (max 100)
`status`	string	Filter by user status (active, inactive, pending)

Headers

Name	Type	Description
`Authorization`required	string	Bearer token for authentication

Response200

json

{
  "data": [
    {
      "id": "usr_123abc",
      "email": "john@example.com",
      "name": "John Doe",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42
  }
}

Create User

POST/api/v1/users

Creates a new user in your organization.

Headers

Name	Type	Description
`Authorization`required	string	Bearer token for authentication
`Content-Type`required	string	Must be application/json

Request Body

json

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "member"
}

Responses

201User created successfully

json

{
  "id": "usr_456def",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "member",
  "status": "pending",
  "created_at": "2024-01-20T14:22:00Z"
}

400Invalid request body

json

{
  "error": "validation_error",
  "message": "Email is required"
}

409User already exists

json

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

Get User

GET/api/v1/users/{id}

Retrieves a single user by their unique identifier.

Path Parameters

Name	Type	Description
`id`required	string	The user's unique identifier

Headers

Name	Type	Description
`Authorization`required	string	Bearer token for authentication

Responses

200User found

json

{
  "id": "usr_123abc",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "admin",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "last_login": "2024-01-20T09:15:00Z"
}

404User not found

json

{
  "error": "not_found",
  "message": "User not found"
}

Delete User

DELETE/api/v1/users/{id}

Permanently deletes a user from your organization. This action cannot be undone.

Path Parameters

Name	Type	Description
`id`required	string	The user's unique identifier

Headers

Name	Type	Description
`Authorization`required	string	Bearer token for authentication

Responses

204User deleted successfully

404User not found

json

{
  "error": "not_found",
  "message": "User not found"
}

403Insufficient permissions

json

{
  "error": "forbidden",
  "message": "You do not have permission to delete this user"
}