User API Endpoint

0

Users management controls access to your account as well as access to various groups of content for your readers. In a general sense, there are staff users as well as non-staff user user (readers).

Each user can be assigned a User Role to determine their overall access to your application.

User_groups are also used to include certain types of (typically non-staff) users into groups which control access to your content (categories and articles).

Using the User API, you can programmatically organize user objects from your own applications and scripts. Possible uses include controlling access to content and users, importing data from external sources, or exporting content for backup or any other purpose.


The user object


Attributes

user_id

This is the unique numeric reference for the user object. This can be used to identity a user in a number of API calls

This value is immutable and cannot be changed.

email

This is the primary identifier that a user will reference when logging into the system and also where they will be notified of system events.

This should only be assigned to valid email addresses

first_name

The user's first name or given name and is used in greetings as well as when identifying them by their profile or when messaging.

last_name

The user's last name or family name.

role

The role that the user has been assigned. All users are assigned some role, whether it is a non-staff "READER" role or one of the available staff roles.

This will be one of:

  • READER - a basic non-staff user with no permissions or privileges within the system (although can be assigned to various groups if desired by a staff member)
  • EDITOR - a staff content editor, able to create and edit categories and articles
  • MANAGER - includes all of the permissions of an editor, but also includes permission to add and edit users
  • ADMIN - includes all of the permissions of a manager, but also includes access to account, billing and API Key creation functionality
enabled

A boolean value of true or false indicating whether the user is enabled or not.

Users that are not enabled cannot log into the system.

Note that when this attribute is edited, it will only take effect when the user next logs in.

If the user is currently active within the system, they will continue to retain their access until they log out or their access token expires.

approved

A boolean value of true or false indicating whether the user has been approved by a manager or admin.

This approval is only necessary when admin settings specify that user approval is required. Enabling this approval method prevents unwanted users automatically gaining access to your published content.

User that are awaiting approval will not be permitted to access the system and will instead receive a message indicating their approval is pending. Managers and admins will receive notification of any pending approvals in their dashboard.

last_login

A Unix timestamp representing the last time the user logged into the system

 Language: json
{
	"user_id": 4,
	"email": "example@gogoworx.com",
	"first_name": "John",
	"last_name": "Doe",
	"role", "Manager",
	"enabled": true,
	"approved": true,
	"last_login": 1590186487
}



⯁


Retrieve a userGET /user

Returns one or more users matching the specified criteria

Required parameters

None. If no parameters are specified, all users for the current account will be returned.


Optional parameters

user_id

Unique numeric identifier for a specific user object to be returned.

first_name

When specified, results will be filtered to return only users with matching first_name values.

last_name

When specified, results will be filtered to return only users with matching last_name values.

role

The role that the user has been assigned. All users are assigned some role, whether it is a non-staff "READER" role or one of the available staff roles.

When specified, this should be one of the following values and will filter the results to only return users that have the specified role (see the example to the right):

  • READER - a basic non-staff user with no permissions or privileges within the system (although can be assigned to various groups if desired by a staff member)
  • EDITOR - a staff content editor, able to create and edit categories and articles
  • MANAGER - includes all of the permissions of an editor, but also includes permission to add and edit users
  • ADMIN - includes all of the permissions of a manager, but also includes access to account, billing and API Key creation functionality
limit

Optional limit on the number of objects to be returned, between 1 and 100

If this parameter is not provided, a default limit of 100 will be applied, returning the maximum of 100 items.

fetch_offset

A cursor to use for pagination. Defines the numeric offset from where results should begin being fetched.

For example, if you were working with a large number of records, and wanted to fetch them in pages of 10 at a time, you might set the limit value to 10 (indicating only 10 records at a time should be returned) and for the first page, fetch_offset would be 0 to indicate no offset (returning records 1-10).

For the second page, fetch_offset would be set to 10, allowing records 11-20 to be returned.

If this parameter is not provided, a default fetch_offset of 0 will be applied, returning records from the start of the result set.

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/user \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"role": "EDITOR", "limit": 20}'

Response (containing specified objects):

 Language: json
[{
	"user_id": 345,
	"email": "johndoe@example.com",
	"first_name": "John",
	"last_name": "Doe",
	"role", "EDITOR",
	"enabled": true,
	"approved": true,
	"last_login": 1590186487
},
{
	"user_id": 346,
	"email": "timbrown@example.com",
	"first_name": "Tim",
	"last_name": "Brown",
	"role", "EDITOR",
	"enabled": true,
	"approved": true,
	"last_login": 1590186487
}]



⯁


Update a userPUT /user

Updates a single, specified user based on the parameters provided

Required parameters

user_id

Unique numeric identifier for the user to be updated.

This value is immutable and cannot be changed.


Optional parameters

email

This is the primary identifier that a user will reference when logging into the system and also where they will be notified of system events.

This should only be assigned to valid email addresses

first_name

The user's first name or given name and is used in greetings as well as when identifying them by their profile or when messaging.

last_name

The user's last name or family name.

enabled

A boolean value of true or false indicating whether the user is enabled or not.

Users that are not enabled cannot log into the system.

Note that when this attribute is edited, it will only take effect when the user next logs in.

If the user is currently active within the system, they will continue to retain their access until they log out or their access token expires.

approved

A boolean value of true or false indicating whether the user has been approved by a manager or admin.

This approval is only necessary when admin settings specify that user approval is required. Enabling this approval method prevents unwanted users automatically gaining access to your published content.

Users that are awaiting approval will not be permitted to access the system and will instead receive a message indicating their approval is pending. Managers and admins will receive notification of any pending approvals in their dashboard.

 Language: bash [ Line Numbers Enabled ]
curl -X PUT https://api.gogoworx.com/user \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"user_id": 346, "first_name": "Frank", "email": "frankbrown@example.com"}'

Response (containing the updated object):

 Language: json
[{
	"user_id": 346,
	"email": "frankbrown@example.com",
	"first_name": "Frank",
	"last_name": "Brown",
	"role", "EDITOR",
	"enabled": true,
	"approved": true,
	"last_login": 1590186487
}]



⯁


Delete a userDELETE /user

Deletes a single, specified user based on the specified user_id.

Note that once deleted, a user can no longer be accessed, nor can they log into the application again. If you simply intend to disable a user instead, update the enabled flag or modify user_group settings for the user to limit their access to content.

Required parameters

The user_id parameter must be specified to uniquely identify the user to be deleted


Optional parameters

None
 Language: bash [ Line Numbers Enabled ]
curl -X DELETE https://api.gogoworx.com/user \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"user_id": 346}'

Response (containing empty array):

 Language: json
[]