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).
A color tag on the API method indicates the server to which you should make the request.

  • 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.

API endpoint

The methods are called via HTTPS on the register or core server depending on the method:

  • Register: https://reg.{domain} or https://{hostname}/reg for DNS-less setup.
  • Core: https://{core-subdomain}.{domain} or https://{hostname} for DNS-less setup.

You can adapt the examples with "API" selector in the top navigation bar.

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

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 {register}/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 {register}/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 {register}/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 {register}/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 {register}/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.
You need to use the availableCore URL as endpoint for the Create user API method.

 

Get apps

HTTP-onlyGET {register}/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 {register}/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 {core}/users

Creates a new user account. The method's parameters can be customized with the system streams configuration.

Before Pryv.io 1.6, this route was served by the register server on /user

Parameters

appId
string

Your app's unique identifier.

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.

language
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.

apiEndpoint
string

The apiEndpoint to reach this account. It includes a personal access token.

 

Check username

HTTP-onlyGET {register}/{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 {register}/{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 {register}/{email}/username

Get the username of a Pryv.io account according to the given email. This API method can be disabled in the platform configuration.

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).

 

Get core

HTTP-onlyGET {register}/cores

Get the core of a Pryv.io account according to the given username or email. You must provide only one of them.

Parameters

username
string

The username to look for.

email
string

The email to look for. When using the email parameter, you will always get a core returned, even if no such email is registered.
This is meant to prevent email discovery.

Result

HTTP200 OK
core
object

The core by username

 

Delete user

HTTP-onlyDELETE {core}/users/{username}Trusted apps only 

Deletes a user account. This method must be enabled in the platform configuration. You should fetch the URL of the core where the user data is stored using the Get core method.

  • When performed by the account owner, this method requires a personal token.
  • For platform administrators, please refer to its Delete user method.
  • For Open Pryv.io users, this method requires to provide the auth:adminAccessKey as Authorization header.

Parameters

username
stringHTTPset in request path

The username of the account to delete.

Result

HTTP200 OK
userDeletion
object

The deleted user.