System reference

Basics

This document describes Pryv.io's system-level API, allowing developers to create and manage user accounts.

Services involved

Unlike user account data, which is fully managed by the core server hosting each account, managing the accounts themselves (e.g. retrieval, creation, deletion) is handled by the core servers and the central register server (AKA user account directory).

  • The core servers own the account management processes, i.e. data creation and deletion
  • The register server maintains the list of account usernames and their hosting locations; it helps account management by providing checks (for creation) and is notified of all relevant changes by the core servers.

Account creation

The steps for creating a new Pryv.io account are the following:

  1. The client calls the register server to get a list of available hostings (core server locations), see Get Hostings.
  2. The client calls the URL under "availableCore" for the hosting it chose with the desired new account data, see Create user.
  3. Data is verified.
  4. If validation passes, the user is saved and an authenticated apiEndpoint is returned to the caller. See app guidelines.

(DEPRECATED) Please use the new account creation flow described above.

  1. Client calls the register server to get a list of available hostings (core server locations), see Get Hostings.
  2. Client calls register server with desired new account data (including which core server should host the account), see Create user.
  3. register server verifies data, hands it over to specified core server if OK
  4. Core server verifies data, creates account if OK (sending welcome email to user), returns status (including created account id) to register server
  5. register server updates directory if OK, returns status to client

API methods

The methods are called via HTTPS on the register server: https://reg.{domain} or https://{hostname}/reg for DNS-less setup.

Admin

Admin only 

Methods for platform administration.

These calls are limited to accredited persons and are flagged as Admin only.

Admin api calls are tagged with A

They must carry the admin key in the HTTP Authorization header.
This key is defined within the platform configuration: REGISTER_ADMIN_KEY.

 

Get users

AHTTP-onlyGET /admin/users

Get the list of all users registered on the platform.

Parameters

toHTML
booleanoptional

If true, format the resulting users list as HTML tables.

Result

HTTP200 OK
users
array

Array of user data.

 

Get core servers

AHTTP-onlyGET /admin/servers

Get the list of all core servers with the number of users on them.

Parameters

Result

HTTP200 OK
servers
object

Object mapping each available core server to its user count.

 

Get users on core server

AHTTP-onlyGET /admin/servers/{serverName}/users

Get the list of all users registered on a specific core server.

Parameters

serverName
stringHTTPset in request path

The name of the core server.

Result

HTTP200 OK
users
array

Array of user data.

 

Rename core server

AHTTP-onlyGET /admin/servers/{srcServerName}/rename/{dstServerName}

Rename a core server, thus reassigning the users from srcServer to dstServer.

Parameters

srcServerName
stringHTTPset in request path

The current name of the core server to rename.

dstServerName
stringHTTPset in request path

The new name of the core server.

Result

HTTP200 OK
count
number

The count of reassigned users. It can be 0 if srcServerName did not match any existing core server.

Specific errors

INVALID_DATA
HTTP400

The server name (source or destination) is invalid because of an unrecognized format.

Service

Methods for collecting service information such as details about the platform and the API, connected apps or hostings (core server locations).

 

Get hostings

HTTP-onlyGET /hostings

Get the list of all available hostings for data storage locations.

Parameters

Result

HTTP200 OK
regions
Object

Object containing multiple regions, containing themselves multiple zones, containing themselves multiple hostings.
The value you need to use as hosting parameter in the users.create method is a key of the hostings object.

 

Get apps

HTTP-onlyGET /apps

Retrieve the list of applications connected to the platform.

Parameters

Result

HTTP200 OK
apps
array

An array listing all the applications connected to the Pryv.io platform.

 

Get app

HTTP-onlyGET /apps/{appid}

Retrieve information about a given application.

Parameters

appid
stringHTTPset in request path

The id of the application to look for.

Result

HTTP200 OK
app
object

An object listing information about the given application.

Users

Methods for managing users.

 

Create user

HTTP-onlyPOST /user

(DEPRECATED) Please use the new create user method.

Creates a new user account on the specified core server.

Parameters

appid
string

Your app's unique identifier.

hosting
string

The name of the core server that should host the account, see Get Hostings.

username
string

The user's username.

password
string

The user's password.

email
string

The user's e-mail address, used for password retrieval.

invitationtoken
stringoptional

An invitation token, necessary when users registration is limited to a specific set of users. Platform administrators may limit users registration by configuring a list of authorized invitation tokens. If this is not the case, users registration is open to everyone and this parameter can be omitted.

YAvailable in entreprise only.

languageCode
stringoptional

The user's preferred language as a 2-letter ISO language code.

referer
stringoptional

A referer id potentially used for analytics.

Result

HTTP200 OK
username
string

A confirmation of the user's username.

server
string

(DEPRECATED) Please use the apiEndpoint parameter.

The server where this account is hosted. The result will be invalid for DNS-less setups.

apiEndpoint
string

The apiEndpoint to reach this account. Does not include an access token.

 

Check username

HTTP-onlyGET /{username}/check_username

For the single node mode please use this API endpoint.

Check the availability and validity of a given username.

Parameters

username
stringHTTPset in request path

The username to check.

Result

HTTP200 OK
reserved
boolean

Set to true if the given username is already taken, false otherwise.

reason
stringoptional

Optional indication of the reason why the username is reserved. If it mentions RESERVED_USER_NAME, this means that the given username is part of the reserved usernames list configured within the register service.

Specific errors

INVALID_USERNAME
HTTP400

The given username is invalid because of an unrecognized format.

 

Check email existence

HTTP-onlyGET /{email}/check_email

Check the existence of an account's email.

Parameters

email
stringHTTPset in request path

The email address to check.

Result

HTTP200 OK
exists
boolean

Set to true if the email address is already registered, false otherwise.

Specific errors

INVALID_EMAIL
HTTP400

The email address is invalid because of an unrecognized format.

 

Get username from email

HTTP-onlyGET /{email}/username

Get the username of a Pryv.io account according to the given email.

Parameters

email
stringHTTPset in request path

The email address to look for.

Result

HTTP200 OK
username
string

The username linked to the given email.

Specific errors

UNKNOWN_EMAIL
HTTP404

The given email address is unknown (unregistered).