Users API Reference

Overview

The Users API offers tools for managing user accounts on your Publica.la platform. It includes functionality for creating, updating, deactivating, and reactivating users, as well as managing user sessions and permissions.

info

Make sure you generated the api_token on your store. More info in the API Authentication guide

Endpoint Reference

Endpoint	Method	Description
/integration-api/v1/dashboard/users	POST	Create a new user
/integration-api/v1/dashboard/users	GET	List or search for users
/integration-api/v1/dashboard/users/(id)	PUT	Update an existing user
/integration-api/v1/dashboard/users/(id)	DELETE	Deactivate a user
/integration-api/v1/dashboard/users/(id)/re-activate	PUT	Reactivate a user
/integration-api/v1/users/(id)/force-logout	POST	Force user logout

Create a User

Create a new user account on the platform.

Endpoint: POST /integration-api/v1/dashboard/users/

Request Fields

Field	Type	Description	Required
email	string	User's email address	Yes
external_id	string	Your unique identifier for this user	Yes
new_password	string	User's password	Recommended
sessions_limit	integer	Limit of simultaneous sessions (max 999999)	No
assign_new_plan	integer	Plan ID to assign to the user	No
new_plan_custom_valid_to	string	Plan expiration date (YYYY-MM-DD)	No
admin	boolean	Whether user has admin privileges	No
plan_admin	boolean	Whether user has plan admin privileges	No
only_sees_readable	boolean	Whether user only sees readable content	No

Example Request

{
   "email": "[email protected]",
   "external_id": "user-id-in-your-platform",
   "new_password": "Abcd1234",
   "sessions_limit": null,
   "assign_new_plan": null,
   "new_plan_custom_valid_to": "",
   "admin": false,
   "plan_admin": false,
   "only_sees_readable": true
}

Response Fields

Field	Description	Type
CODE	Response status code	string
data.id	User ID	integer
data.email	User email	string
data.uuid	Unique user identifier	string
data.picture	User profile picture URL	string
data.admin	Admin status	boolean
data.plan_admin	Plan admin status	boolean
data.only_sees_readable	Whether user only sees readable content	boolean
data.sessions_limit	User session limit	integer
data.created_at	Creation timestamp	object
data.updated_at	Last update timestamp	object
data.deleted_at	Deletion timestamp (if applicable)	object

Example Response

{
    "CODE": "success",
    "data": {
        "id": 923242,
        "email": "[email protected]",
        "uuid": "af5af4f9-9b8d-4d79-b162-0cec4279cae5",
        "picture": "https://www.gravatar.com/avatar/5c472faa5105266a3d41aee277eb9d0c?s=160&d=mm&r=g",
        "admin": false,
        "plan_admin": false,
        "only_sees_readable": false,
        "sessions_limit": null,
        "created_at": {
            "timestamp": 1620931649,
            "date": "2021-05-13 18:47:29",
            "timezone": "UTC"
        },
        "updated_at": {
            "timestamp": 1621256387,
            "date": "2021-05-17 12:59:47",
            "timezone": "UTC"
        },
        "deleted_at": null
    }
}

Response Codes

Code	Description
200	User created successfully
422	Validation error (details in response)
401	Unauthorized (invalid API token)

Retrieve Users

List or search for users.

Endpoint: GET /integration-api/v1/dashboard/users

Query Parameters

Parameter	Description	Example
query=email	Filter by user email	/integration-api/v1/dashboard/users/[email protected]
query=deactivated	Show only deactivated users	/integration-api/v1/dashboard/users/?query=deactivated
query=admins	Show only admin users	/integration-api/v1/dashboard/users/?query=admins

Response

The response includes detailed user information and pagination metadata when listing multiple users.

Example Response (List)

{
"CODE": "success",
    "data": {
        "paginator": {
            "current_page": 1,
            "data": [
                {
                    "id": 923242,
                    "uuid": "af5af4f9-9b8d-4d79-b162-0cec4279cae5",
                    "admin": false,
                    "plan_admin": false,
                    "email": "[email protected]",
                    "sessions_limit": 1,
                    "only_sees_readable": 1,
                    "picture": "https://www.gravatar.com/avatar/98789c9d5825d6f6c6615313ffcaf1ac?s=160&d=mm&r=g",
                    "created_at": "2021-05-18T13:28:53.000000Z",
                    "updated_at": "2021-05-18T13:28:53.000000Z",
                    "deleted_at": null,
                    "purchased_issues_with_cancelled_count": 0,
                    "user_plans_count": 0,
                    "can_be_edited": true,
                    "created_at_date_string": "2021-05-18",
                    "impersonate": "https://example.publica.la/impersonate/take/53114",
                    "sessions": null,
                    "ip_ranges": [],
                    "referrers": [],
                    "purchased_issues_with_cancelled": [],
                    "user_plans": []
                },
                // ... more users ...
            ],
            // ... pagination fields ...
        }
    }
}

Response Codes

Code	Description
200	Success
404	User not found
401	Unauthorized (invalid API token)

Update a User

Update an existing user's information.

Endpoint: PUT /integration-api/v1/dashboard/users/(id)

Request Fields

Field	Type	Description	Required
email	string	User's email address	Yes
external_id	string	Your unique identifier for this user	Yes
new_password	string	User's new password	No
sessions_limit	integer	Limit of simultaneous sessions	No
assign_new_plan	integer	Plan ID to assign to the user	No
new_plan_custom_valid_to	string	Plan expiration date (YYYY-MM-DD)	No
admin	boolean	Whether user has admin privileges (1 or 0)	No
plan_admin	boolean	Whether user has plan admin privileges (1 or 0)	No
only_sees_readable	boolean	Whether user only sees readable content (1 or 0)	Yes
user_plan_name	string	Name for the user's plan	No

Response Codes

Code	Description
204	User updated successfully
422	Validation error (details in response)
401	Unauthorized (invalid API token)

Deactivate a User

Deactivate a user, preventing them from logging in.

Endpoint: DELETE /integration-api/v1/dashboard/users/(id)

important

A deactivated user cannot log in through any means until reactivated.

Example Request

• DELETE /integration-api/v1/dashboard/users/923242

Response

{
    "CODE": "success",
    "data": []
}

Response Codes

Code	Description
200	User deactivated successfully
404	User not found
401	Unauthorized (invalid API token)

Reactivate a User

Reactivate a previously deactivated user.

Endpoint: PUT /integration-api/v1/dashboard/users/(id)/re-activate

Example Request

• PUT /integration-api/v1/dashboard/users/923242/re-activate

Response

{
    "CODE": "success",
    "data": 1
}

Response Codes

Code	Description
200	User reactivated successfully
404	User not found
401	Unauthorized (invalid API token)

Force User Logout

Force a user to log out of all active sessions.

Endpoint: POST /integration-api/v1/users/(id)/force-logout

important

After logging out, the user will be redirected to the initial URL on their next interaction with the system.

The endpoint accepts either the numeric ID or the external_id as the user identifier. Note that if the external-auth-token is used, the external_id is the UUID contained in the token.

Example Request

• POST /integration-api/v1/users/923242/force-logout

Response Codes

Code	Description
200	User logged out successfully
404	User not found
401	Unauthorized (invalid API token)

Related API Documentation

• Orders API: Manage customer orders and permissions
• Content API: Manage content products
• Plans API: Create and manage subscription plans