User Management API

API for programmatic user management within an organization

The User Management API enables partners and resellers to programmatically manage users within their organization. This API is ideal for automated user provisioning when someone signs up on a partner platform.

Authentication

This API uses Organization API Keys (not User API Keys). These keys are created by organization administrators and have the prefix sk_meingpt_um_.

curl -X GET "https://app.meingpt.com/api/user-management/v1/users" \
  -H "Authorization: Bearer sk_meingpt_um_..."

Rate Limiting

All API keys have a rate limit of 100 requests/minute. Rate limit information is returned in response headers:

  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Unix timestamp when limit resets

Creating API Keys

Organization API keys can be created by administrators through the settings. The key is only displayed once at creation.

Attention

Store your API key securely. It cannot be displayed again.

Endpoints

List Users

GET /api/user-management/v1/users

Query Parameters:

  • page (optional): Page number (default: 1)
  • pageSize (optional): Users per page (default: 20, max: 100)
  • search (optional): Search by email, first name, or last name

Response:

{
  "status": "success",
  "users": [
    {
      "id": "user_123",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLogin": "2024-01-20T14:22:00Z",
      "isAdmin": false,
      "teams": [
        { "id": "dept_456", "name": "Marketing" }
      ]
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}

Get User Details

GET /api/user-management/v1/users/:userId

Create New User

POST /api/user-management/v1/users

Request Body:

{
  "email": "new.user@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Response:

{
  "status": "success",
  "user": { ... },
  "isNewUser": true
}

Note

If the user already exists, they will be added to the organization and isNewUser will be false.

Add Existing User

POST /api/user-management/v1/users/add

Request Body:

{
  "email": "existing@example.com"
}

Remove User

DELETE /api/user-management/v1/users/:userId

Attention

Admin users cannot be removed via the API.

Change User Role

Switches a user between MEMBER (occupies a seat) and VIEWER (observer — no seat). Ideal for automatically setting users to observer when a program ends (freeing the license) and back to member when they resume.

PATCH /api/user-management/v1/users/:userId/role

Request Body:

{
  "role": "VIEWER"
}

Response:

{
  "status": "success",
  "user": { ... }
}

Note

VIEWER (observer) does not occupy a seat. Switching to MEMBER assigns a seat automatically — if no seats are available, the API responds with 412.

Attention

The role of admin users cannot be changed via the API. ADMIN is not assignable via the API.

List Teams

GET /api/user-management/v1/teams

Response:

{
  "status": "success",
  "teams": [
    {
      "id": "dept_456",
      "name": "Marketing",
      "isDefault": false,
      "memberCount": 12
    }
  ]
}

Create Team

POST /api/user-management/v1/teams

Request Body:

{
  "name": "Sales"
}

Response:

{
  "status": "success",
  "team": {
    "id": "dept_789",
    "name": "Sales",
    "isDefault": false,
    "memberCount": 0
  }
}

Note

Team names must be unique within the organization.

Delete Team

DELETE /api/user-management/v1/teams/:teamId

Attention

The default team cannot be deleted. All users are automatically removed from the team before deletion.

Add User to Team

POST /api/user-management/v1/teams/:teamId/users

Request Body:

{
  "userId": "user_123"
}

Remove User from Team

DELETE /api/user-management/v1/teams/:teamId/users/:userId

Error Handling

The API returns structured error responses:

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

HTTP Status Codes:

  • 400 - Invalid input
  • 401 - Invalid or missing API key
  • 403 - Feature not enabled or permission denied
  • 404 - Resource not found
  • 409 - Conflict (e.g., user already a member)
  • 429 - Rate limit exceeded
  • 500 - Server error
Was this page helpful?