Skip to main content

​
Introduction

The Users API provides comprehensive endpoints for managing users, roles, and permissions in the Blog Marketing Platform. This API allows you to list users, update their information, change roles, manage status, and delete users.

​
Base URL

GET /api/v1/users

​
Authentication

All Users API endpoints require authentication. Include your access token in the Authorization header: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
User Object

The User object represents a user in the system with the following structure:
​
id
number
required
Unique identifier for the user
​
username
string
required
Unique username for the user
​
email
string
required
User’s email address
​
firstName
string
required
User’s first name
​
lastName
string
required
User’s last name
​
role
string
required
User’s role in the system. Available roles:
  • administrador - Full system access
  • editor - Can publish and edit any post
  • autor - Can create and edit own posts
  • escritor - Can create posts (equivalent to autor)
  • comentador - Can only comment and react
​
avatar
string
required
URL to user’s avatar image
​
status
string
required
Current user status. One of: active, inactive, suspended
​
lastLogin
string
required
ISO 8601 timestamp of user’s last login
​
createdAt
string
required
ISO 8601 timestamp of when the user was created
​
permissions
array
required
Array of permission strings the user has access to
​
stats
object
User statistics object
​
postsCreated
number
Total number of posts created by the user
​
commentsApproved
number
Total number of comments approved by the user
​
usersManaged
number
Total number of users managed (admin only)
​
postsEdited
number
Total number of posts edited
​
postsPublished
number
Total number of posts published
​
commentsModerated
number
Total number of comments moderated
​
totalViews
number
Total views across all user’s content

​
Example User Object

{
  "id": 1,
  "username": "admin_master",
  "email": "[email protected]",
  "firstName": "Juan",
  "lastName": "Pérez",
  "role": "administrador",
  "avatar": "https://images.pexels.com/photos/2379004/pexels-photo-2379004.jpeg",
  "status": "active",
  "lastLogin": "2024-01-15T10:30:00Z",
  "createdAt": "2023-06-01T00:00:00Z",
  "permissions": [
    "admin_completo",
    "asignar_roles",
    "crear_post",
    "editar_post_cualquiera",
    "publicar_post"
  ],
  "stats": {
    "postsCreated": 45,
    "commentsApproved": 234,
    "usersManaged": 12,
    "postsPublished": 42,
    "totalViews": 125430
  }
}

​
Available Roles

The system supports the following roles with their corresponding IDs:
Role IDRole NameDescription
1administradorFull system access, can manage users and assign roles
2editorCan publish posts, edit any post, moderate comments
3autorCan create and edit own posts
4comentadorCan only comment and react to posts
The roles creador and escritor are mapped to autor (ID: 3) in the backend.

​
Rate Limiting

API requests are rate-limited to ensure system stability:
  • Standard users: 100 requests per minute
  • Authenticated users: 1000 requests per minute
  • Admin users: 5000 requests per minute

​
Error Handling

The Users API uses standard HTTP response codes:
Status CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid authentication
403Forbidden - Insufficient permissions
404Not Found - User doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Next Steps

User CRUD Operations

Learn how to list, update, delete users and manage roles

User Profiles

Manage user profiles, activity tracking, and social links

Build docs developers (and LLMs) love

Get started for freeTalk to us