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:

The client calls the register server to get a list of available hostings (core server locations), see Get Hostings.
The client calls the URL under “availableCore” for the hosting it chose with the desired new account data, see Create user.
Data is verified.
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.

Client calls the register server to get a list of available hostings (core server locations), see Get Hostings.
Client calls register server with desired new account data (including which core server should host the account), see Create user.
register server verifies data, hands it over to specified core server if OK
Core server verifies data, creates account if OK (sending welcome email to user), returns status (including created account id) to register server
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

Aidusers.getHTTP-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.

Fetching the users list for a Pryv.io platform

{}

⬇

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    },
    {
      "username": "user2",
      "email": "user2@gmail.com",
      "language": "fr",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001bldp292u45lvr",
      "registeredTimestamp": "1536930239805",
      "server": "core2.pryv.me",
      "registeredDate": "Fri, 14 Sep 2018 13:03:59 GMT"
    }
  ]
}

curl -i "https://reg.pryv.me/admin/users"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    },
    {
      "username": "user2",
      "email": "user2@gmail.com",
      "language": "fr",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001bldp292u45lvr",
      "registeredTimestamp": "1536930239805",
      "server": "core2.pryv.me",
      "registeredDate": "Fri, 14 Sep 2018 13:03:59 GMT"
    }
  ]
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/admin/users"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    },
    {
      "username": "user2",
      "email": "user2@gmail.com",
      "language": "fr",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001bldp292u45lvr",
      "registeredTimestamp": "1536930239805",
      "server": "core2.pryv.me",
      "registeredDate": "Fri, 14 Sep 2018 13:03:59 GMT"
    }
  ]
}

Get core servers

Aidservers.getHTTP-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.

Fetching the core servers list for a Pryv.io platform

{}

⬇

{
  "servers": {
    "core1.pryv.me": 1337,
    "core2.pryv.me": 42
  }
}

curl -i "https://reg.pryv.me/admin/servers"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "servers": {
    "core1.pryv.me": 1337,
    "core2.pryv.me": 42
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/admin/servers"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "servers": {
    "core1.pryv.me": 1337,
    "core2.pryv.me": 42
  }
}

Get users on core server

Aidservers.users.getHTTP-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.

Fetching the users list for a specifc core server.

{
  "serverName": "core1.pryv.me"
}

⬇

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    }
  ]
}

curl -i "https://reg.pryv.me/admin/servers/core1.pryv.me/users"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    }
  ]
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/admin/servers/core1.pryv.me/users"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "users": [
    {
      "username": "user1",
      "email": "red.miller@mail.ch",
      "language": "en",
      "invitationToken": "enjoy",
      "referer": "null",
      "id": "cmofxw7vr001aldp20m9y2wq3",
      "registeredTimestamp": "1557743399558",
      "server": "core1.pryv.me",
      "registeredDate": "Mon, 13 May 2019 10:29:59 GMT"
    }
  ]
}

Rename core server

Aidservers.renameHTTP-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`	HTTP`400` The server name (source or destination) is invalid because of an unrecognized format.

Renaming a core server.

{
  "srcServerName": "core1.pryv.me",
  "dstServerName": "core2.pryv.me"
}

⬇

{
  "count": 1
}

curl -i "https://reg.pryv.me/admin/servers/core1.pryv.me/rename/core2.pryv.me"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "count": 1
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/admin/servers/core1.pryv.me/rename/core2.pryv.me"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "count": 1
}

Service

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

Get hostings

idhostings.getHTTP-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.

Fetching the hostings for a Pryv.io platform

{}

⬇

{
  "regions": {
    "europe": {
      "name": "Europe",
      "localizedName": {
        "fr": "Europe"
      },
      "zones": {
        "switzerland": {
          "name": "Switzerland",
          "localizedName": {
            "fr": "Suisse"
          },
          "hostings": {
            "core1": {
              "url": "https://my-hosting-provider.ch",
              "name": "Pilot core server",
              "description": "The single PoC core server",
              "available": true,
              "availableCore": "https://my-core.ch"
            }
          }
        }
      }
    }
  }
}

curl -i "https://reg.pryv.me/hostings"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "regions": {
    "europe": {
      "name": "Europe",
      "localizedName": {
        "fr": "Europe"
      },
      "zones": {
        "switzerland": {
          "name": "Switzerland",
          "localizedName": {
            "fr": "Suisse"
          },
          "hostings": {
            "core1": {
              "url": "https://my-hosting-provider.ch",
              "name": "Pilot core server",
              "description": "The single PoC core server",
              "available": true,
              "availableCore": "https://my-core.ch"
            }
          }
        }
      }
    }
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/hostings"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "regions": {
    "europe": {
      "name": "Europe",
      "localizedName": {
        "fr": "Europe"
      },
      "zones": {
        "switzerland": {
          "name": "Switzerland",
          "localizedName": {
            "fr": "Suisse"
          },
          "hostings": {
            "core1": {
              "url": "https://my-hosting-provider.ch",
              "name": "Pilot core server",
              "description": "The single PoC core server",
              "available": true,
              "availableCore": "https://my-core.ch"
            }
          }
        }
      }
    }
  }
}

Get apps

idapps.getHTTP-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.

Retrieving the list of applications connected to the platform.

{}

⬇

{
  "apps": [
    {
      "id": "pryv-csv-importer",
      "displayName": "CSV Importer",
      "description": "Import existing data from CSV files",
      "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
      "appURL": "http://pryv.github.io/dev-tools/csv-importer",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
    },
    {
      "id": "ifttt-all",
      "displayName": "IFTTT",
      "description": "Connect Pryv to over 100 other products and services with Pryv Recipes on IFTTT",
      "iconURL": "https://pryv.github.io/static-web/apps/ifttt-all/icon512.png",
      "appURL": "https://ifttt.com/pryv",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "https://ifttt.com/pryv"
    }
  ]
}

curl -i "https://reg.pryv.me/apps"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "apps": [
    {
      "id": "pryv-csv-importer",
      "displayName": "CSV Importer",
      "description": "Import existing data from CSV files",
      "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
      "appURL": "http://pryv.github.io/dev-tools/csv-importer",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
    },
    {
      "id": "ifttt-all",
      "displayName": "IFTTT",
      "description": "Connect Pryv to over 100 other products and services with Pryv Recipes on IFTTT",
      "iconURL": "https://pryv.github.io/static-web/apps/ifttt-all/icon512.png",
      "appURL": "https://ifttt.com/pryv",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "https://ifttt.com/pryv"
    }
  ]
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/apps"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "apps": [
    {
      "id": "pryv-csv-importer",
      "displayName": "CSV Importer",
      "description": "Import existing data from CSV files",
      "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
      "appURL": "http://pryv.github.io/dev-tools/csv-importer",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
    },
    {
      "id": "ifttt-all",
      "displayName": "IFTTT",
      "description": "Connect Pryv to over 100 other products and services with Pryv Recipes on IFTTT",
      "iconURL": "https://pryv.github.io/static-web/apps/ifttt-all/icon512.png",
      "appURL": "https://ifttt.com/pryv",
      "active": false,
      "onboarding": false,
      "category": "Other",
      "support": [
        "iPad",
        "iPhone",
        "Web"
      ],
      "settingsPageURL": "https://ifttt.com/pryv"
    }
  ]
}

Get app

idapps.getOneHTTP-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.

Retrieving information about a given application.

{}

⬇

{
  "app": {
    "id": "pryv-csv-importer",
    "displayName": "CSV Importer",
    "description": "Import existing data from CSV files",
    "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
    "appURL": "http://pryv.github.io/dev-tools/csv-importer",
    "active": false,
    "onboarding": false,
    "category": "Other",
    "support": [
      "iPad",
      "iPhone",
      "Web"
    ],
    "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
  }
}

curl -i "https://reg.pryv.me/apps/${appid}"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "app": {
    "id": "pryv-csv-importer",
    "displayName": "CSV Importer",
    "description": "Import existing data from CSV files",
    "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
    "appURL": "http://pryv.github.io/dev-tools/csv-importer",
    "active": false,
    "onboarding": false,
    "category": "Other",
    "support": [
      "iPad",
      "iPhone",
      "Web"
    ],
    "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/apps/${appid}"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "app": {
    "id": "pryv-csv-importer",
    "displayName": "CSV Importer",
    "description": "Import existing data from CSV files",
    "iconURL": "https://pryv.github.io/static-web/apps/pryv-csv-importer/icon512.png",
    "appURL": "http://pryv.github.io/dev-tools/csv-importer",
    "active": false,
    "onboarding": false,
    "category": "Other",
    "support": [
      "iPad",
      "iPhone",
      "Web"
    ],
    "settingsPageURL": "http://pryv.github.io/dev-tools/csv-importer"
  }
}

Users

Methods for managing users.

Create user

idusers.createHTTP-onlyPOST {core}/users

Creates a new user account. The method’s parameters can be customized with the system streams configuration. Enforces password complexity rules if enabled (set via the corresponding platform settings).

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

Specific errors

`invalid-parameters-format`	HTTP`400` The password does not match password complexity rules (if enabled).

Creating a user.

{
  "appId": "default",
  "password": "ChjUzDXwaTG2qdV",
  "email": "joseph-brenner@pryv.me",
  "invitationToken": "o3in4o2",
  "language": "en",
  "referer": "hospital-A"
}

⬇

{
  "username": "user-123-abc",
  "apiEndpoint": "https://{personal-token}@user-123-abc.pryv.me/"
}

curl -i -X POST -H 'Content-Type: application/json' -d '{"appId":"default","username":"user-123-abc","password":"ChjUzDXwaTG2qdV","email":"joseph-brenner@pryv.me","invitationToken":"o3in4o2","language":"en","referer":"hospital-A"}' "https://{core-subdomain}.pryv.me/users"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "username": "user-123-abc",
  "apiEndpoint": "https://{personal-token}@user-123-abc.pryv.me/"
}

Only available for HTTP REST

Only available for HTTP REST

curl -i -X POST -H 'Content-Type: application/json' -d '{"appId":"default","username":"user-123-abc","password":"ChjUzDXwaTG2qdV","email":"joseph-brenner@pryv.me","invitationToken":"o3in4o2","language":"en","referer":"hospital-A"}' "https://{core-subdomain}.pryv.me/users?auth=${token}"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "username": "user-123-abc",
  "apiEndpoint": "https://{personal-token}@user-123-abc.pryv.me/"
}

Check username

idusername.checkHTTP-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`	HTTP`400` The given username is invalid because of an unrecognized format.

Checking availability and validity of a given username

{}

⬇

{
  "reserved": false
}

curl -i "https://reg.pryv.me/user-123-abc/check_username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "reserved": false
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/user-123-abc/check_username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "reserved": false
}

Special case where the username is part of the reserved list.

{}

⬇

{
  "reserved": true,
  "reason": "RESERVED_USER_NAME"
}

curl -i "https://reg.pryv.me/pryvpryv/check_username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "reserved": true,
  "reason": "RESERVED_USER_NAME"
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/pryvpryv/check_username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "reserved": true,
  "reason": "RESERVED_USER_NAME"
}

Check email existence

idemails.checkHTTP-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`	HTTP`400` The email address is invalid because of an unrecognized format.

Checking the existence of an account’s email address.

{
  "email": "joseph-brenner@pryv.me"
}

⬇

{
  "exists": false
}

curl -i "https://reg.pryv.me/joseph-brenner@pryv.me/check_email"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "exists": false
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/joseph-brenner@pryv.me/check_email"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "exists": false
}

Get username from email

idemail.username.getHTTP-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`	HTTP`404` The given email address is unknown (unregistered).

Retrieving a username from a given email.

{
  "email": "joseph-brenner@pryv.me"
}

⬇

{
  "username": "user-123-abc"
}

curl -i "https://reg.pryv.me/joseph-brenner@pryv.me/username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "username": "user-123-abc"
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/joseph-brenner@pryv.me/username"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "username": "user-123-abc"
}

Get core

idcores.getHTTP-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

Retrieving the core URL for a given username.

{}

⬇

{
  "core": {
    "url": "https://co1.pryv.me/"
  }
}

curl -i "https://reg.pryv.me/cores?username=trench"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "core": {
    "url": "https://co1.pryv.me/"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/cores?username=trench"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "core": {
    "url": "https://co1.pryv.me/"
  }
}

Retrieving the core URL for a non-existing email.

{
  "email": "adam-gibson@replacement.tech"
}

⬇

{
  "core": {
    "url": "https://co3.pryv.me/"
  }
}

curl -i "https://reg.pryv.me/cores?email=adam-gibson@replacement.tech"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "core": {
    "url": "https://co3.pryv.me/"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://reg.pryv.me/cores?email=adam-gibson@replacement.tech"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "core": {
    "url": "https://co3.pryv.me/"
  }
}

Delete user

idusers.deleteHTTP-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.

Deleting a user.

{}

⬇

{
  "userDeletion": {
    "username": "mark-kaminski"
  }
}

curl -i -X DELETE "https://{core-subdomain}.pryv.me/users/mark-kaminski"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "userDeletion": {
    "username": "mark-kaminski"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i -X DELETE "https://{core-subdomain}.pryv.me/users/mark-kaminski?auth=${token}"

⬇

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Version: 2.0.0-pre

{
  "userDeletion": {
    "username": "mark-kaminski"
  }
}

Create access request

idaccess.createHTTP-onlyPOST {register}/reg/access

Creates a new access authorization request. The requesting app calls this method, then polls the returned URL until the user accepts or refuses the request. This implements the Pryv.io OAuth-like authorization flow.

Parameters

`requestingAppId`	string The id of the app requesting access.
`requestedPermissions`	array of permission objects The permissions requested by the app.
`returnURL`	stringoptional An optional URL to redirect the user to after accepting or refusing.
`clientData`	objectoptional Optional metadata the requesting app wants to attach to the request.

Result

HTTP201 Created

`status`	string The current status of the request (`NEED_SIGNIN`).
`key`	string The polling key. Use it to poll and to build the auth URL.
`poll`	string The full URL to poll for status updates.
`poll_rate_ms`	number The recommended polling interval in milliseconds.

Poll access request

idaccess.pollHTTP-onlyGET {register}/reg/access/{key}

Polls the status of a pending access request. The requesting app calls this periodically until it receives ACCEPTED, REFUSED, or ERROR.

Possible statuses: NEED_SIGNIN (waiting), ACCEPTED (token issued), REFUSED, ERROR.

Parameters

`key`	stringHTTPset in request path The polling key returned by Create access request.

Result

HTTP200 OK

`status`	string The current status.
`username`	string (When `ACCEPTED`) The username that granted the access.
`token`	string (When `ACCEPTED`) The personal or app token.
`apiEndpoint`	string (When `ACCEPTED`) The API endpoint for subsequent requests.

Accept/Refuse access request

idaccess.updateHTTP-onlyPOST {register}/reg/access/{key}

Updates the state of an access request. Called by the auth page after the user has signed in and accepted or refused the permissions.

Parameters

`key`	stringHTTPset in request path The polling key.
`status`	string The new status: `ACCEPTED`, `REFUSED`, `ERROR`, or `REDIRECTED`.
`username`	string (Required when `ACCEPTED`) The username granting the access.
`token`	string (Required when `ACCEPTED`) The token for the access.

Result

HTTP200 OK

`status`	string The updated status.

Check invitation token

idinvitationtoken.checkHTTP-onlyPOST {register}/access/invitationtoken/check

Checks whether an invitation token is valid. Returns plain text true or false. Used when user registration is limited to holders of valid invitation tokens.

Parameters

`invitationtoken`	string The invitation token to verify.

Result

HTTP200 OK

	string Plain text: `true` if valid, `false` otherwise.

List invitation tokens

idinvitations.listHTTP-onlyGET {register}/reg/admin/invitationsAdmin only

Lists all invitation tokens configured on the platform. Requires admin authorization.

Result

HTTP200 OK

`invitations`	array The list of invitation tokens.

Generate invitation tokens

idinvitations.generateHTTP-onlyGET {register}/reg/admin/invitations/postAdmin only

Generates new invitation tokens. Requires admin authorization.

Parameters

`count`	numberHTTPquery parameter Number of tokens to generate (default: 1).
`message`	stringoptionalHTTPquery parameter Optional description for the generated tokens.

Result

HTTP200 OK

`data`	object The generated invitation tokens.

Update DNS records

iddns.recordsHTTP-onlyPOST {register}/reg/recordsAdmin only

Admin endpoint for updating runtime DNS entries (e.g. ACME challenge records for SSL certificate provisioning). Records are persisted to PlatformDB and propagated to all cores in a multi-core deployment. Requires admin authorization.

Parameters

`subdomain`	string The subdomain to set records for.
`records`	object The DNS records to set (e.g. `{ "TXT": "challenge-value" }`).

Result

HTTP200 OK

`subdomain`	string The subdomain.
`status`	string `ok` on success.