Admin reference

Basics

This document describes Pryv.io's administration API, allowing to configure the platform parameters and manage platform users.
This service is only available with an Entreprise license.

Administration service

The administration service has its own API and authentication mechanism.

Authorization

All requests for retrieving and manipulating admin data must carry a valid JSON web token that is obtained at login.

It must be assigned to the authorization header.

API methods

The methods are called via HTTPS on the administration server: https://lead.{domain}.

Authentication

Methods for authenticating admin users.

 

Login user

HTTP-onlyPOST /auth/login

Authenticates the user against the provided credentials.

Parameters

username
string

The user's username

password
string

The user's password

Result

HTTP200 OK
token
string

JSON web token to use for further API calls.

 

Logout user

HTTP-onlyPOST /auth/logout

Terminates a session by invalidating its JSON web token (the user will have to login again). Simply provide the JSON web token in own of the the supported ways, no request body is required.

Result

HTTP200 OK

Admin users

Methods for managing admin users.

 

Retrieve admin users information

HTTP-onlyGET /users

Retrieves the admin users information.

Parameters

Result

HTTP200 OK
users
Array of admin users

The admin users information.

 

Retrieve admin user information

HTTP-onlyGET /users/{username}

Retrieves the admin user's information.

Parameters

username
stringHTTPset in request path

The username of the admin user.

Result

HTTP200 OK
user

The admin user's information.

 

Create an admin user

HTTP-onlyPOST /users

Creates an admin user.

Parameters

username
string

The username of the admin user.

password
string

The password of the admin user.

permissions
string

Result

HTTP200 OK
user

The created admin user's information.

 

Update an admin user's permissions

HTTP-onlyPUT /users/{username}/permissions

Updates an admin user's permissions.

Parameters

permissions

The permissions of the admin user.

Result

HTTP200 OK
user

The updated admin user's information.

 

Reset an admin user's password

HTTP-onlyPOST /users/{username}/reset-password

Resets an admin user's password.

Parameters

username
stringHTTPset in request path

The username of the admin user for whom to reset the password.

Result

HTTP200 OK
password
string

The admin user's new password.

 

Delete admin user

HTTP-onlyDELETE /users/{username}

Delete admin account.

Parameters

username
stringHTTPset in request path

The username of the admin user to delete.

Result

HTTP200 OK
username
string

The username of the deleted platform user.

Platform settings

Methods for managing platform settings.

 

Retrieve platform settings

HTTP-onlyGET /admin/settings

Retrieves the platform settings.

Result

HTTP200 OK
settings
object

The platform settings.

 

Update platform settings

HTTP-onlyPUT /admin/settings

Updates the platform settings and saves them.

Parameters

update
objectHTTPrequest body

New values for the platform settings.

Result

HTTP200 OK
settings
object

The updated platform settings.

Specific errors

invalid-input
HTTP400

The configuration format is invalid.

 

Apply settings changes

HTTP-onlyPOST /admin/notify

Reboots desired services with latest platform settings.

Parameters

services
array of stringsoptional

The Pryv.io services to reboot. If empty, reboots all Pryv.io services. See your configuration's docker-compose file for the list of services.

Result

HTTP200 OK
successes
array of machines

Machines successfully updated.

url
string

The url of the machine.

role
string

The role of the machine (core, static, reg).

failures
array of machines

Machines failed to update.

url
string

The url of the machine.

role
string

The role of the machine (core, static, reg).

error
object

The error information.

Platform users

Methods for managing platform users.

 

Retrieve platform user information

HTTP-onlyGET /platform-users/{username}

Retrieves the platform user's information.

Parameters

username
stringHTTPset in request path

The username of the platform user.

Result

HTTP200 OK
user

The platform user's information.

 

Delete user

HTTP-onlyDELETE /platform-users/{username}

Delete user account from the Pryv.io platform. This deletion is final.

Parameters

username
stringHTTPset in request path

The username of the platform user to delete.

Result

HTTP200 OK
username
string

The username of the deleted platform user.

Data structure

Admin user

An admin user's information.

username
string

An admin user's username.

permissions
array of strings

Admin permissions

An admin user's permissions.

users
array of strings

Permissions over admin users.
Available permissions: read, create, delete, resetPassword, changePermissions.

settings
array of strings

Permissions over platform settings.
Available permissions: read, update.

platformUsers
array of strings

Permissions over platform users.
Available permissions: read, delete.

Platform user

A platform user's information.

username
string

The platform user's username.

email
string

The platform user's email.

language
string

The platform user's preferred language.

invitationToken
string

The invitation token provided at registration by the platform user.

referer
string

The referer provided at registration by the platform user.

registeredTimestamp
string

The UNIX timestamp of the platform user's registration.

server
string

The URL of the core machine where the platform user's data is stored.

registeredDate
string

The readable timestamp of the platform user's registration.