1House Global API Documentation

User Roles & Permissions

Manage user roles, permissions, and access control

Manage user roles, permissions, and access control for the platform.

Permission-Based Access Control

The platform uses a permission-based access control system. Users have a permissions array that contains specific permission strings. Roles are conceptual groupings of permissions, but access is determined by the permissions array.

Overview

The Permissions API provides:

  • User permission management
  • Permission assignment and removal
  • Permission distribution and statistics
  • User count by permission
  • Role-based permission grouping

Base Path: /v1/user

User Permissions

Get User Permissions

Get all permissions for a specific user.

GET /v1/user/:userId/permissions

Headers:

  • X-API-Key: Your API key
  • Authorization: Bearer JWT token (for user requests) or X-Internal-API-Key (for service-to-service calls)

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token"
const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions',
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();
import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "permissions": ["educator", "read_courses", "write_courses"]
  }
}

Assign Permissions to User

Add permissions to a user's permissions array.

POST /v1/user/:userId/permissions/assign

Request Body:

{
  "permissions": ["educator", "read_courses"]
}

Example Request:

curl -X POST "https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions/assign" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["educator", "read_courses"]
  }'
const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions/assign',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      permissions: ['educator', 'read_courses'],
    }),
  }
);

const data = await response.json();
import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions/assign"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}
data = {
    "permissions": ["educator", "read_courses"]
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

Unassign Permissions from User

Remove permissions from a user's permissions array.

POST /v1/user/:userId/permissions/unassign

Request Body:

{
  "permissions": ["educator"]
}

Set User Permissions (Replace All)

Replace all permissions for a user. This completely replaces the existing permissions array.

PUT /v1/user/:userId/permissions

Request Body:

{
  "permissions": ["educator", "read_courses", "write_courses", "delete_courses"]
}

Replace All Permissions

This endpoint replaces ALL existing permissions. Make sure to include all permissions the user should have, not just the new ones.

Permission Statistics

Get Permission Distribution

Get a count of users for each permission.

GET /v1/user/permissions/distribution

Headers:

  • X-API-Key: Your API key
  • Authorization: Bearer JWT token (admin only) or X-Internal-API-Key (for service-to-service calls)

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/user/permissions/distribution" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token"
const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/user/permissions/distribution',
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();
import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/user/permissions/distribution"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "educator": 45,
    "read_courses": 120,
    "write_courses": 30,
    "delete_courses": 5,
    "admin": 3
  }
}

Get User Count by Permission

Get the count of users who have a specific permission.

GET /v1/user/permissions/:permission/count

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/user/permissions/educator/count" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token"

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "count": 45
  }
}

Filtering Users by Permissions

Get Users with Specific Permission

Get all users who have a specific permission in their permissions array.

GET /v1/user?permissions=educator

Query Parameters:

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberResults per page (default: 10)
searchstringSearch by name or email
permissionsstringComma-separated list of permissions to filter by (users must have at least one)

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/user?permissions=educator&page=1&limit=20" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token"

Permission Filtering

When filtering by permissions, users must have at least one of the specified permissions in their permissions array. Use comma-separated values to filter by multiple permissions (e.g., permissions=educator,admin).

Common Permissions

Common permission strings used in the platform:

  • educator - Can create and manage courses
  • admin - Full platform access
  • moderator - Content moderation access
  • read_courses - Read access to courses
  • write_courses - Create and update courses
  • delete_courses - Delete courses
  • read_livestreams - Read access to livestreams
  • write_livestreams - Create and manage livestreams
  • read_users - Read user information
  • write_users - Create and update users
  • read_wallets - Read wallet information
  • write_wallets - Manage wallets

Internal Service Authentication

Service-to-service calls can use the X-Internal-API-Key header instead of JWT tokens:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/user/507f1f77bcf86cd799439011/permissions" \
  -H "X-API-Key: your-development-api-key" \
  -H "X-Internal-API-Key: your-internal-api-key"

Error Handling

401 Unauthorized

{
  "success": false,
  "status": 401,
  "message": "No token provided"
}

403 Forbidden

{
  "success": false,
  "status": 403,
  "message": "Insufficient permissions"
}

404 Not Found

{
  "success": false,
  "status": 404,
  "message": "User not found"
}

Best Practices

Use Permissions Instead of Roles

The platform uses a permission-based system. Instead of checking for roles, check for specific permissions in the user's permissions array.

Assign Permissions Incrementally

Use assign to add permissions and unassign to remove them, rather than replacing all permissions unless necessary.

Cache Permission Distribution

Permission distribution data can be cached on the client side and refreshed periodically to reduce API calls.

Validate Permissions on Backend

Always validate permissions on the backend. Frontend permission checks are for UI purposes only.

Password Reset

Comprehensive guide for the forgot password flow

Platform TypesNew

Supported platforms for authentication and service access (SKU-based)

On this page

OverviewUser PermissionsGet User PermissionsAssign Permissions to UserUnassign Permissions from UserSet User Permissions (Replace All)Permission StatisticsGet Permission DistributionGet User Count by PermissionFiltering Users by PermissionsGet Users with Specific PermissionCommon PermissionsInternal Service AuthenticationError Handling401 Unauthorized403 Forbidden404 Not FoundBest PracticesUse Permissions Instead of RolesAssign Permissions IncrementallyCache Permission DistributionValidate Permissions on BackendRelated Documentation