Users API

The Users API allows you to manage user accounts, profiles, and permissions in your Wortfreunde organization.

Endpoints

Get Current User Profile

Retrieve the profile of the authenticated user.

GET /users/profile

Response

{
  "id": "usr_123abc",
  "email": "[john@example.com](mailto:john@example.com)",
  "name": "John Doe",
  "role": "editor",
  "organization": {
    "id": "org_456def",
    "name": "Example Company"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "last_login": "2024-03-15T14:22:00Z"
}

Update User Profile

Update the current user's profile information.

PUT /users/profile

Request Body

{
  "name": "John Smith",
  "timezone": "Europe/Berlin",
  "language": "de",
  "notification_preferences": {
    "email": true,
    "push": false
  }
}

List All Users

List all users in your organization. Requires admin permissions.

GET /users

Query Parameters

Parameter	Type	Description
role	string	Filter by role (admin, editor, viewer)
status	string	Filter by status (active, inactive, invited)
search	string	Search by name or email
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)

Example Request

GET /users?role=editor&status=active&page=1&limit=50

Response

{
  "data": [
    {
      "id": "usr_123abc",
      "email": "[editor@example.com](mailto:editor@example.com)",
      "name": "Jane Editor",
      "role": "editor",
      "status": "active",
      "last_login": "2024-03-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 23,
    "pages": 1
  }
}

Get Specific User

Retrieve details of a specific user by ID.

GET /users/{id}

Response

{
  "id": "usr_123abc",
  "email": "[user@example.com](mailto:user@example.com)",
  "name": "User Name",
  "role": "editor",
  "status": "active",
  "permissions": [
    "articles.read",
    "articles.write",
    "articles.publish"
  ],
  "metadata": {
    "department": "Marketing",
    "employee_id": "EMP123"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-03-10T15:45:00Z"
}

Create New User

Create a new user account. Requires admin permissions.

POST /users

Request Body

{
  "email": "[newuser@example.com](mailto:newuser@example.com)",
  "name": "New User",
  "role": "editor",
  "send_invitation": true,
  "permissions": [
    "articles.read",
    "articles.write"
  ],
  "metadata": {
    "department": "Content Team"
  }
}

Response

{
  "id": "usr_789xyz",
  "email": "[newuser@example.com](mailto:newuser@example.com)",
  "name": "New User",
  "role": "editor",
  "status": "invited",
  "invitation_sent_at": "2024-03-15T16:00:00Z"
}

Update User

Update an existing user's information. Requires admin permissions.

PUT /users/{id}

Request Body

{
  "name": "Updated Name",
  "role": "admin",
  "status": "active",
  "permissions": [
    "articles.read",
    "articles.write",
    "articles.publish",
    "articles.delete"
  ]
}

Delete User

Remove a user from the organization. Requires admin permissions.

DELETE /users/{id}

Response

204 No Content

User Roles

Role	Description	Default Permissions
admin	Full access to all resources	All permissions
editor	Create and edit content	Read, write, publish articles
viewer	Read-only access	Read articles and analytics

Permissions

Fine-grained permissions can be assigned to users:

Article Permissions

• articles.read - View articles
• articles.write - Create and edit articles
• articles.publish - Publish articles
• articles.delete - Delete articles

User Permissions

• users.read - View user profiles
• users.write - Create and edit users
• users.delete - Delete users

Analytics Permissions

• analytics.read - View analytics data
• analytics.export - Export analytics reports

System Permissions

• system.settings - Manage organization settings
• system.billing - Manage billing and subscriptions
• system.api_keys - Manage API keys

User Status

Status	Description
active	User can access the system
inactive	User account is disabled
invited	User has been invited but hasn't accepted
suspended	User is temporarily suspended

Code Examples

JavaScript

// List all active editors
const editors = await client.users.list({
  role: 'editor',
  status: 'active'
});

// Create a new user
const newUser = await client.users.create({
  email: '[content@example.com](mailto:content@example.com)',
  name: 'Content Manager',
  role: 'editor',
  send_invitation: true
});

// Update user permissions
await client.users.update(userId, {
  permissions: [
    'articles.read',
    'articles.write',
    'articles.publish',
    'analytics.read'
  ]
});

Python

# Get current user profile
profile = client.users.get_profile()
print(f"Logged in as: {profile.name}")

# Search for users
users = client.users.list(
    search="john",
    status="active"
)

# Update user role
client.users.update(
    user_id,
    role="admin"
)

Webhooks

Subscribe to user-related events:

• user.created - New user created
• user.updated - User profile updated
• user.deleted - User removed
• user.login - User logged in
• user.role_changed - User role modified

Best Practices

1. Principle of Least Privilege: Assign only necessary permissions
2. Regular Audits: Review user access periodically
3. Strong Authentication: Enforce strong passwords and 2FA
4. Activity Monitoring: Track user actions via audit logs
5. Offboarding: Immediately deactivate accounts when users leave

Next Steps

• See authentication guide for API access