User management

Documentation for all functionality to manage users (usernames) using the Revive Adserver REST API (get a list of all users in an account, get a specific user, add a user, modify a user, delete a user, set the permissions of a user).

getUserListByAccountId

Description: Get a list of all existing users in an account, by providing the account ID

Implementation: URL/usr/acc/[accountId]

Method: GET

Json example

Method: 
    GET http://api.example.com/usr/acc/X

Response example

[
    {
        "userId": "21",
        "contactName": "John Doe",
        "emailAddress": "[email protected]",
        "username": "johndoe",
        "password": null,
        "defaultAccountId": "2",
        "active": "1"
    },
abbreviated for clarity, additional entries could appear here
]

Note

Note the terms account and agency are related but different. Due to a terminology change, end users see accounts in the user interface, but these used to be called ‘agency’ in the past. For reasons of backward compatibility, the API continues to use the term agency.

The ID to be used in the request is the account ID of the agency. Please consult the documentation about managing accounts to find out how agencies and accounts are tied together.

In most cases, account ID 1 is reserved for the ‘system administrator’ type account.

getUser

Description: Get the detail of a specific user, requesting by user ID

Implementation: URL/usr/[userId]

Method: GET

Json example

Method: 
    GET http://api.example.com/usr/4

Response example

{
    "userId": "21",
    "contactName": "John Doe",
    "emailAddress": "[email protected]",
    "username": "johndoe",
    "password": null,
    "defaultAccountId": "2",
    "active": "1"
}

addUser

Description: Add a new user

Implementation: URL/usr/new

Method: POST/PUT

addUser
Name Description allowed values Optional/Required
contactName name of the user string required
emailAddress email address string required
defaultAccountId id of the user’s default account int required
username username string required
password password password required (see notes)
active is the user active 0/1 optional

 

Json example

Method: 
    POST http://api.example.com/usr/new
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "contactName": "John Doe",
        "emailAddress": "[email protected]",
        "defaultAccountId": 2,
        "username": "johndoe",
        "password": "somepassword"
    }

Notes

When using the Revive Adserver REST API version 5.1.0 or higher, in combination with Revive Adserver v5.4.0 or higher, the password field is not mandatory. Omitting the password means that the “welcome new user” email gets sent to the new user, containing instructions to set their initial password. See the Release Notes on Revive Adserver REST API v5.1.0 and the Notes on changes to password functionality in Revive Adserver v5.4.0 for more information.

modifyUser

Description: Modify an existing user

Implementation: URL/usr/[userId]

Method: POST/PUT

See the addUser method above for additional information.

deleteUser

Description: Delete an existing user

Implementation: URL/usr/[userId]

Method: DELETE

Json example

Method:

DELETE http://api.example.com/usr/X

setPermissions

Description: Set the permissions of a user relative to an account

Implementation: URL/usr/[userId]/lnk

Method: POST

Json example

Method:

POST http://api.example.com/usr/X/link

Request Header:

Content-Type:text/javascript

Request Body:

{
  "type": "ADMIN|MANAGER|ADVERTISER|TRAFFICKER",
  "accountId": X,
  "permissions": [
    10,
    12
   ]
}

Notes

The setPermissions method is new starting with Revive Adserver REST API v5.1.0 and works only in combination with Revive Adserver v5.4.0 or higher.

A list of values allowed for permissions can be found in the Github repository of the Revive Adserver software. In the example above, the values 10 indicates that the user has the ‘super account’ permission, meaning the user is allowed to create, manage, and delete other usernames. The value 12 indicates that the user has permission to delete inventory items.

Each POST will reset the permissions, so an empty array as permissions, or even omitting it will do the trick of removing the permissions of an existing user.

At the time of this writing, it is not yet possible to ‘unlink’ a user from an account using the Revive Adserver REST API, nor to retrieve the user’s permissions and linked accounts.

Current version

The most recently released version of the Revive Adserver REST API is v5.1.0 (publication date April 15, 2022).

See Release Notes

Compatibility

Revive Adserver REST API is compatible with all versions of Revive Adserver v4.x, v5.0.x, v5.1.x, v5.2.x, v5.3.x, and v5.4.x. It may also be compatible with Revive Adserver v3.x (and also with OpenX Source v2.8 and higher), but this can not be guaranteed.

Revive Adserver REST API is compatible with all supported versions of PHP, including PHP 7 and PHP  8.

Also see Technical Requirements, Product Content, and Installation Instructions.

Our Recent Tweets