Users Endpoints

Manage users and their permissions.

List Users

Get all users.

GET /api/v1/users

Query Parameters

Parameter	Type	Description
role	string	Filter by role: Admin, Operator, Viewer
search	string	Search by username or email
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)

Response

Success (200):

{
  "users": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "Admin",
      "mfa_enabled": true,
      "oauth_provider": null,
      "last_login": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "username": "operator",
      "email": "operator@example.com",
      "role": "Operator",
      "mfa_enabled": false,
      "oauth_provider": "github",
      "last_login": "2024-01-15T09:00:00Z",
      "created_at": "2024-01-05T00:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20
}

Example

curl "https://bloqd.example.com/api/v1/users?role=Admin" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get User

Get a specific user by ID.

GET /api/v1/users/{userId}

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Response

Success (200):

{
  "id": 1,
  "username": "admin",
  "email": "admin@example.com",
  "role": "Admin",
  "mfa_enabled": true,
  "oauth_provider": null,
  "server_access": "all",
  "last_login": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-10T00:00:00Z"
}

---

Create User

Create a new user.

POST /api/v1/users

Request Body

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "SecurePassword123!",
  "role": "Operator"
}

Response

Success (201):

{
  "id": 6,
  "username": "newuser",
  "email": "newuser@example.com",
  "role": "Operator",
  "created_at": "2024-01-15T10:30:00Z"
}

Validation Rules

• Username: 3-50 characters, alphanumeric and underscores
• Email: Valid email format
• Password: Minimum 8 characters, at least one uppercase, lowercase, and number
• Role: Admin, Operator, or Viewer

---

Update User

Update an existing user.

PATCH /api/v1/users/{userId}

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Request Body

{
  "email": "updated@example.com",
  "role": "Admin"
}

Response

Success (200):

{
  "id": 6,
  "username": "newuser",
  "email": "updated@example.com",
  "role": "Admin",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

Delete User

Delete a user.

DELETE /api/v1/users/{userId}

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Response

Success (200):

{
  "message": "User deleted successfully"
}

warning

You cannot delete your own account or the last admin user.

---

Reset User Password

Reset a user's password (admin only).

POST /api/v1/users/{userId}/reset-password

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Request Body (Optional)

{
  "new_password": "NewSecurePassword123!"
}

If no password provided, a random one is generated.

Response

Success (200):

{
  "message": "Password reset successfully",
  "temporary_password": "TempPass123!"
}

---

Reset User MFA

Reset a user's MFA (admin only).

POST /api/v1/users/{userId}/reset-mfa

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Response

Success (200):

{
  "message": "MFA reset successfully",
  "mfa_enabled": false
}

---

Set Server Access

Configure which servers a user can access.

PUT /api/v1/users/{userId}/server-access

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Request Body

{
  "access_type": "specific",
  "server_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Access types:

• all - Access to all servers
• specific - Access only to specified servers

Response

Success (200):

{
  "message": "Server access updated",
  "access_type": "specific",
  "server_count": 2
}

---

Get User Sessions

Get active sessions for a user.

GET /api/v1/users/{userId}/sessions

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Response

Success (200):

{
  "sessions": [
    {
      "id": "sess-abc123",
      "ip_address": "192.168.1.50",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2024-01-15T08:00:00Z",
      "last_activity": "2024-01-15T10:30:00Z",
      "current": true
    },
    {
      "id": "sess-def456",
      "ip_address": "10.0.0.5",
      "user_agent": "curl/7.68.0",
      "created_at": "2024-01-14T15:00:00Z",
      "last_activity": "2024-01-14T16:00:00Z",
      "current": false
    }
  ]
}

---

Terminate User Session

Terminate a specific user session.

DELETE /api/v1/users/{userId}/sessions/{sessionId}

Path Parameters

Parameter	Type	Description
userId	integer	User ID
sessionId	string	Session ID

Response

Success (200):

{
  "message": "Session terminated"
}

---

Terminate All Sessions

Terminate all sessions for a user.

DELETE /api/v1/users/{userId}/sessions

Path Parameters

Parameter	Type	Description
userId	integer	User ID

Query Parameters

Parameter	Type	Description
except_current	boolean	Keep current session (default: true)

Response

Success (200):

{
  "message": "Sessions terminated",
  "terminated_count": 3
}

---

List API Keys

Get API keys for a user.

GET /api/v1/users/{userId}/keys

Response

Success (200):

{
  "keys": [
    {
      "id": 1,
      "name": "CI/CD Integration",
      "prefix": "f2b_abc...",
      "permissions": "write",
      "last_used": "2024-01-15T10:00:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

---

Create API Key

Create an API key for a user.

POST /api/v1/users/{userId}/keys

Request Body

{
  "name": "New Integration",
  "permissions": "read",
  "expires_at": "2024-12-31T23:59:59Z"
}

Response

Success (201):

{
  "id": 2,
  "name": "New Integration",
  "key": "f2b_xyz123...",
  "permissions": "read",
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}

caution

The full API key is only shown once. Save it securely.