System API

APISystem APIAdmin API

API:Pryv Lab: ${username}.pryv.meDNS-less: ${hostname}/${username}Own domain: ${username}.${domain}

Format:REST payloadBatch blockcURLcURL authSocket.IO

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 the platform setting auth.adminAccessKey. A call without it, or with another value, answers 404 unknown-resource, as if the route did not exist.

Get users

Aidusers.getHTTP-onlyGET {core}/system/admin/users

Get the list of all users registered on the platform.

Parameters

Result

HTTP200 OK

users	array of objects One object per user: username, id, email and language, plus core, the URL of the core that hosts the account, on a multi-core platform.

Fetching the users list for a Pryv.io platform

{}

⬇︎

{
  "users": [
    {
      "username": "user1",
      "id": "c000000000000000000000046",
      "email": "red.miller@mail.ch",
      "language": "en"
    },
    {
      "username": "user2",
      "id": "c000000000000000000000047",
      "email": "user2@gmail.com",
      "language": "fr"
    }
  ]
}

curl -i "https://${token}@${username}.pryv.me/system/admin/users"

⬇︎

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

{
  "users": [
    {
      "username": "user1",
      "id": "c000000000000000000000046",
      "email": "red.miller@mail.ch",
      "language": "en"
    },
    {
      "username": "user2",
      "id": "c000000000000000000000047",
      "email": "user2@gmail.com",
      "language": "fr"
    }
  ]
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://${username}.pryv.me/system/admin/users?auth=${token}"

⬇︎

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

{
  "users": [
    {
      "username": "user1",
      "id": "c000000000000000000000046",
      "email": "red.miller@mail.ch",
      "language": "en"
    },
    {
      "username": "user2",
      "id": "c000000000000000000000047",
      "email": "user2@gmail.com",
      "language": "fr"
    }
  ]
}

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": "c000000000000000000000046",
      "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": "c000000000000000000000046",
      "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": "c000000000000000000000046",
      "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.
externalIds	number The number of external-id index rows moved to the new core name (from open-pryv.io 2.0.0-rc.60). Run the rename with the renamed core stopped: a claim it commits after the rename would still carry the old name.

Specific errors

INVALID_DATA	HTTP400 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,
  "externalIds": 0
}

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,
  "externalIds": 0
}

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,
  "externalIds": 0
}

External ids

Admin only 

Namespaces of external ids and the release of an id claimed by the wrong account. Served by every core under /system/admin/ (not by the register server), with the admin key. The guide explains the model, the blinding and the procedures.

List external-id namespaces

AidextIdNamespaces.listHTTP-onlyGET {core}/system/admin/ext-id-ns

Lists the namespaces of the platform (from open-pryv.io 2.0.0-rc.58). The salt of a namespace is never returned. Not audited (a read).

Parameters

Result

HTTP200 OK

namespaces	array of objects One object per namespace, ordered by name: namespace (the name), createdAt (a timestamp), label (shown to users on the auth page) and defaultMode (hint or forced).

Listing the namespaces

{}

⬇︎

{
  "namespaces": [
    {
      "namespace": "clinic-ehr",
      "createdAt": 1792800000,
      "label": "Clinic patient record",
      "defaultMode": "hint"
    }
  ]
}

curl -i "https://${token}@${username}.pryv.me/system/admin/ext-id-ns"

⬇︎

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

{
  "namespaces": [
    {
      "namespace": "clinic-ehr",
      "createdAt": 1792800000,
      "label": "Clinic patient record",
      "defaultMode": "hint"
    }
  ]
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://${username}.pryv.me/system/admin/ext-id-ns?auth=${token}"

⬇︎

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

{
  "namespaces": [
    {
      "namespace": "clinic-ehr",
      "createdAt": 1792800000,
      "label": "Clinic patient record",
      "defaultMode": "hint"
    }
  ]
}

Get an external-id namespace

AidextIdNamespaces.getHTTP-onlyGET {core}/system/admin/ext-id-ns/{namespace}

Gets one namespace (from open-pryv.io 2.0.0-rc.58), never its salt. Not audited (a read).

Parameters

namespace	stringHTTPset in request path The namespace name.

Result

HTTP200 OK

namespace	object namespace, createdAt, label and defaultMode, as in the list.

Specific errors

invalid-parameters-format	HTTP400 The name does not follow the namespace name rule.
unknown-resource	HTTP404 No namespace has this name.

Getting a namespace

{
  "namespace": "clinic-ehr"
}

⬇︎

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

curl -i "https://${token}@${username}.pryv.me/system/admin/ext-id-ns/clinic-ehr"

⬇︎

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

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i "https://${username}.pryv.me/system/admin/ext-id-ns/clinic-ehr?auth=${token}"

⬇︎

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

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

Create or update an external-id namespace

AidextIdNamespaces.setHTTP-onlyPUT {core}/system/admin/ext-id-ns/{namespace}

Creates the namespace, or updates its label or default mode (from open-pryv.io 2.0.0-rc.58). On creation the server generates the namespace’s salt; it never changes afterwards and is never returned. Answers 201 Created on creation, 200 OK on an update. Audited, without a user.

Parameters

namespace	stringHTTPset in request path The namespace name: 2 to 63 characters, lowercase letters, digits and -, starting with a letter or a digit (^[a-z0-9][a-z0-9-]{1,62}$).
label	stringoptional The name shown to users on the auth page, 1 to 80 characters. Defaults to the namespace name on creation; unchanged on an update when omitted.
defaultMode	hint|forcedoptional The mode of an auth request or a registration that carries an id of this namespace without a mode. Defaults to hint on creation; unchanged on an update when omitted. forced is honoured from open-pryv.io 2.0.0-rc.59.

Result

HTTP201 Created

namespace	object The namespace after the call: namespace, createdAt, label and defaultMode (no salt). The same body comes with 200 OK on an update.

Specific errors

invalid-parameters-format	HTTP400 The name, the label or the default mode does not follow the rules above.

Creating a namespace

{
  "namespace": "clinic-ehr",
  "label": "Clinic patient record"
}

⬇︎

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

curl -i -X PUT -H 'Content-Type: application/json' -d '{"label":"Clinic patient record"}' "https://${token}@${username}.pryv.me/system/admin/ext-id-ns/clinic-ehr"

⬇︎

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

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

Only available for HTTP REST

Only available for HTTP REST

curl -i -X PUT -H 'Content-Type: application/json' -d '{"label":"Clinic patient record"}' "https://${username}.pryv.me/system/admin/ext-id-ns/clinic-ehr?auth=${token}"

⬇︎

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

{
  "namespace": {
    "namespace": "clinic-ehr",
    "createdAt": 1792800000,
    "label": "Clinic patient record",
    "defaultMode": "hint"
  }
}

Delete an external-id namespace

AidextIdNamespaces.deleteHTTP-onlyDELETE {core}/system/admin/ext-id-ns/{namespace}

Deletes the namespace (from open-pryv.io 2.0.0-rc.58). Refused while any account holds an id of the namespace, unless force is set: then only the namespace row goes, and each core’s reconcile (bin/reconcile-user-cores.js --ext-ids) reports its local ids of that namespace and keeps them. A deleted salt cannot be recovered: every id of the namespace is orphaned. Answers 204 No Content. Audited, without a user.

Parameters

namespace	stringHTTPset in request path The namespace name.
force	booleanoptionalHTTPquery parameter true to delete the namespace even though ids of it are held.

Result

HTTP204 No Content

Specific errors

invalid-parameters-format	HTTP400 The name does not follow the namespace name rule.
unknown-resource	HTTP404 No namespace has this name.
external-id-namespace-in-use	HTTP409 Accounts hold ids of the namespace and force is not set.

Release an external id claimed by the wrong account

AidextIdReleaseHTTP-onlyPOST {core}/system/admin/ext-id/release

Removes the link between an id and the account that holds it, so the right account can claim it (from open-pryv.io 2.0.0-rc.60). Send it to the core that holds the id; another core answers 307 with that core in server (and the Location header): send the call again there. The answer never names the account.

The account that held the id gets an account.externalIds.adminRelease entry in its own audit trail (the namespace and the reason, never the value) and, when the platform sends mail, the external-id-released mail with the namespace label and the reason (setting services.email.enabled.externalIdReleased, template services.email.externalIdReleasedTemplate). The holder reads the reason as written: keep it factual and free of anyone else’s data. A failed mail does not undo the release. The call itself is audited without a user. See the guide, Releasing an id claimed by the wrong account.

Parameters

namespace	string The namespace of the id.
blindedValue	string The blinded value of the id, computed as for a claim.
reason	string Why the id is released, 1 to 500 characters, shown to the account that held it.

Result

HTTP200 OK

released	true The id was released.
notified	mail|audit-only mail when the mail to the account was sent, audit-only when only its audit trail records the release: mail not configured, the notice switched off, the account has no email address, or the send failed.

Specific errors

invalid-parameters-format	HTTP400 A parameter is missing or malformed, or the namespace does not exist (the value is never echoed).
unknown-resource	HTTP404 No account holds this id. Also when this core’s index names it for an account that no longer exists here: the reconcile (bin/reconcile-user-cores.js --ext-ids) cleans such a row.

Releasing an id

{
  "namespace": "clinic-ehr",
  "blindedValue": "<blinded value>",
  "reason": "Claimed by the wrong account; the patient will link it again."
}

⬇︎

{
  "released": true,
  "notified": "mail"
}

curl -i -X POST -H 'Content-Type: application/json' -d '{"namespace":"clinic-ehr","blindedValue":"<blinded value>","reason":"Claimed by the wrong account; the patient will link it again."}' "https://${token}@${username}.pryv.me/system/admin/ext-id/release"

⬇︎

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

{
  "released": true,
  "notified": "mail"
}

Only available for HTTP REST

Only available for HTTP REST

curl -i -X POST -H 'Content-Type: application/json' -d '{"namespace":"clinic-ehr","blindedValue":"<blinded value>","reason":"Claimed by the wrong account; the patient will link it again."}' "https://${username}.pryv.me/system/admin/ext-id/release?auth=${token}"

⬇︎

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

{
  "released": true,
  "notified": "mail"
}

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.
externalId	objectoptional A record id of your system to link to the new account: { namespace, blindedValue, mode? }, as in the externalId of the auth request (see External ids). An id nobody holds is linked to the new account. An id another account holds leaves the new account unlinked in hint mode (send the user to sign in with the account that holds it), and refuses the registration with 409 external-id-already-claimed in forced mode, before anything is reserved. A malformed value or an unknown namespace refuse the registration before anything is reserved. Requires an open-pryv.io release later than 2.0.0-rc.56, and 2.0.0-rc.59 or later for the forced mode (an older core refuses it with invalid-parameters-format).

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.
externalIdLinked	booleanoptional Present when the registration carried an externalId: true when the id is now linked to the new account, false when another account holds it or it could not be linked.

Specific errors

invalid-parameters-format	HTTP400 The password does not match password complexity rules (if enabled), or the externalId is malformed or names an unknown namespace (data.param names the field, never the value).
external-id-already-claimed	HTTP409 (externalId in forced mode) Another account holds the id (data: { namespace, reason: 'value-taken' }, never which account). Nothing is reserved: send the user to sign in with the account that holds it.
cross-core-registration-failed	HTTP503 (Multi-core platform) The registration landed on one core for another core’s hosting, and that core could not take it: it is unreachable, or it refused the forward itself. Nothing is created; retry later. A refusal of the registration by that core (e.g. 409 item-already-exists) is answered as that core answered it. From open-pryv.io 2.0.0-rc.62 (earlier releases answer 500 unexpected-error in these cases, and for any refusal by the other core).

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

On multi-node platforms that store identifiers pseudonymised, a node that does not host the requested account answers with a 307 redirect to the account’s home node — the home node URL is also returned in a { "server": "<url>" } JSON body for clients that do not follow redirects automatically. The home node resolves and returns the username. Clients that follow redirects (including the official libraries) handle this transparently; single-node platforms answer directly without a redirect.

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

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/"
  }
}

Get core holding an external id

idextIdCores.getHTTP-onlyPOST {register}/ext-id/cores

Get the base URL of the core holding an external id: the core of the one account that claimed it. It never tells which account. No authentication. On a DNS-less setup the route is https://{hostname}/reg/ext-id/cores.

It is a POST so the blinded value never appears in a URL. An unknown namespace and an id nobody claimed give the same answer, 404 unknown-resource.

Every lookup counts toward a budget per client address (an IPv4 address, or the /64 of an IPv6 address), kept by each core and shared with the refused claims of claim an external id: at most 10 in a one-minute window opened by the first. Past it the lookup is refused with 429 too-many-attempts until the window ends. The address is read through http.trustedProxies.

Parameters

namespace	string The namespace of the id.
blindedValue	string The blinded value of the record id, HMAC(K_namespace, recordId): base64url without padding, 16 to 64 bytes once decoded.

Result

HTTP200 OK

server	string The base URL of the core holding the id.

Specific errors

invalid-parameters-format	HTTP400 The blinded value is malformed. The error never echoes the value.
unknown-resource	HTTP404 The namespace is unknown, or no account holds the id.
too-many-attempts	HTTP429 More than 10 lookups or refused claims within one minute from this client address on this core. The id is not looked up. Retry after the Retry-After header (seconds), also given as error.data.retryAfterSeconds.

Finding the core that holds an external id.

{
  "namespace": "clinic-ehr",
  "blindedValue": "5axJiZtfRrrFmLoDoJc9LWUadGJBz-ByjoE8SAAHBz4"
}

⬇︎

{
  "server": "https://co1.pryv.me/"
}

curl -i -X POST -H 'Content-Type: application/json' -d '{"namespace":"clinic-ehr","blindedValue":"5axJiZtfRrrFmLoDoJc9LWUadGJBz-ByjoE8SAAHBz4"}' "https://reg.pryv.me/ext-id/cores"

⬇︎

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

{
  "server": "https://co1.pryv.me/"
}

Only available for HTTP REST

Only available for HTTP REST

curl -i -X POST -H 'Content-Type: application/json' -d '{"namespace":"clinic-ehr","blindedValue":"5axJiZtfRrrFmLoDoJc9LWUadGJBz-ByjoE8SAAHBz4"}' "https://reg.pryv.me/ext-id/cores"

⬇︎

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

{
  "server": "https://co1.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.
credentialHandoff	stringoptional Ask that the token be delivered through a one-time shared secret rather than returned in the poll. The only accepted value is shared-secret; anything else is a 400 invalid-parameters. When the server understands it, the ACCEPTED poll carries a handoff key instead of token (see Poll access request) and the 201 echoes credentialHandoff back. An older core drops the field and echoes nothing, so the request degrades to inline token delivery.
cmcInvites	array of invite objectsoptional Cross-account messaging invites the user should answer on the auth page, next to the app access: 1 to 8 entries { capabilityUrl, mandatory?, for?, accessName? }, with no other key. capabilityUrl is an absolute http or https URL of at most 2048 characters; mandatory a boolean (default false); for self (default) or target (the account the access is granted for, when the user acts for an account they manage); accessName the name of the data grant minted by accepting the invite, 1 to 256 characters, stored as sent (the server does not use it; the auth page passes it to the accept). A malformed list is a 400 invalid-parameters. The request’s size ceiling (access:maxRequestBytes) still applies. The 201 echoes the normalised list only when the server understood it; an older core drops the field. Requires open-pryv.io 2.0.0-rc.32 or later; accessName requires open-pryv.io 2.0.0-rc.36 or later, and an older core refuses an entry carrying it with 400 invalid-parameters.
actAs	stringoptional Who the access may be granted for, when the user controls other accounts through account delegation: allow (the default behaviour when omitted), deny (the signed-in account only) or a username to preselect. Any other value is a 400 invalid-parameters.
actAsManagedOnly	booleanoptional true when the access must be granted for an account the user manages, never for the signed-in account. Requires actAs (allow or a username): true without actAs or with actAs: 'deny', or a value that is not a boolean, is a 400 invalid-parameters; false is the same as not sending it. A hint the auth page enforces, not the server: the reference auth page lists only managed accounts and, when none can be used, refuses with reasonId: 'MANAGED_ACCOUNT_UNAVAILABLE'. The 201 echoes actAsManagedOnly: true only when the server understood it; an older core drops the field. Requires open-pryv.io 2.0.0-rc.36 or later.

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.
credentialHandoff	stringoptional Echoed as shared-secret only when the request carried it and the server understood it. Its absence tells the app it will receive inline token delivery.
cmcInvites	array of invite objectsoptional Echoed, normalised (mandatory and for filled in, accessName only on an entry that carried it), only when the request carried cmcInvites and the server understood them. The NEED_SIGNIN poll carries the same list for the auth page.
actAsManagedOnly	trueoptional Echoed as true only when the request carried actAsManagedOnly: true and the server understood it. The NEED_SIGNIN poll carries it too, for the auth page.

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, inline delivery) The personal or app token. Absent when the request asked for credentialHandoff: 'shared-secret' and the server delivers a handoff instead.
apiEndpoint	string (When ACCEPTED) The API endpoint for subsequent requests. Token-less when a handoff is delivered.
handoff	objectoptional (When ACCEPTED and the request asked for credentialHandoff) A one-time credential hand-off in place of token, shaped { "type": "shared-secret", "key": "<eventId>.<random>" }. Retrieve the credential exactly once with POST {apiEndpoint}shared-secrets/retrieve (body { "key": "<key>" }, unauthenticated), which returns { "secret": { "username", "token", "apiEndpoint" } }; a second retrieve answers 403 shared-secret-unavailable. See Shared secrets.
cmcInvites	arrayoptional (When NEED_SIGNIN) The request’s normalised cmcInvites, with accessName on the entries that carried it, for the auth page. (When ACCEPTED) The outcome the auth page posted for each invite, in the request’s order: { acceptEventId, dataGrantAccessId?, acceptedFor?: 'self' }, { declined: true } or { reason }, carried with inline and hand-off delivery alike. The outcomes are a hint from the auth page, not verified by the server; each requester learns the truth from its own inbox. Absent when the request carried no invites or the page posted no outcomes.
actAsManagedOnly	trueoptional (When NEED_SIGNIN) true when the request asked that the access be granted for an account the user manages only. Absent otherwise, and never on ACCEPTED.
reasonId	stringoptional (When REFUSED or ERROR) The reason code the auth page posted. REFUSED_MANDATORY_CONSENT means the user declined a mandatory invite of cmcInvites; MANDATORY_CONSENT_FAILED that a mandatory invite could not be accepted (message names the invite and the error id); MANAGED_ACCOUNT_UNAVAILABLE that the request asked for actAsManagedOnly and the user had no managed account to grant the access for (message names the cause).

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.

On a request whose externalId is in forced mode, ACCEPTED is checked before anything is written: the token must be an app access of username and that account must hold the id (see the externalId of the auth request). The token is posted inline; a handoff or externalIdDeclined field is refused with invalid-parameters (HTTP 400). A refused acceptance leaves the request NEED_SIGNIN.

Parameters

key	stringHTTPset in request path The polling key.
status	string The new status: ACCEPTED, REFUSED or ERROR. Any other value is refused with invalid-parameters (HTTP 400); REDIRECTED is no longer accepted since open-pryv.io 2.0.0-rc.36.
username	string (Required when ACCEPTED) The username granting the access.
token	string (Required when ACCEPTED) The token for the access.
cmcInvites	array of outcome objectsoptional (Only with ACCEPTED, only on a request that carried cmcInvites) One outcome per invite of the request, in its order: { acceptEventId, dataGrantAccessId?, acceptedFor?: 'self' }, { declined: true } or { reason } (ids and reasons at most 256 characters). A list of the wrong length or shape, or one sent with another status or on a request without invites, is a 400 invalid-parameters and the request is left unchanged. Served back as cmcInvites in the ACCEPTED bodies.
reasonId	stringoptional (With REFUSED or ERROR) A reason code, stored as given. The reference auth page posts REFUSED_MANDATORY_CONSENT when the user declined a mandatory invite of cmcInvites, before it writes anything, MANDATORY_CONSENT_FAILED when a mandatory invite could not be accepted, with a message naming the invite and the platform’s error id, and MANAGED_ACCOUNT_UNAVAILABLE when the request carried actAsManagedOnly and no account the user manages could be used, with a message naming the cause.

Result

HTTP200 OK

status	string The updated status.

Specific errors

external-id-mismatch	HTTP400 (forced mode) The token is not an app access of username (data.reason: 'token-invalid'), or the account does not hold the id (data.reason: 'not-holder', which counts in the external id lookup budget).
external-id-check-unavailable	HTTP503 (forced mode) The holder check could not run (data.reason says why). Retry.
too-many-attempts	HTTP429 (forced mode) The client address is over the external id budget. The request is left unchanged.

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.

Every check counts toward a budget per client address (an IPv4 address, or the /64 of an IPv6 address), kept by each core: at most 10 checks in a one-minute window opened by the first. Past it the check is refused with 429 too-many-attempts until the window ends. The address is read through http.trustedProxies.

Parameters

invitationtoken	string The invitation token to verify.

Result

HTTP200 OK

	string Plain text: true if valid, false otherwise.

Specific errors

too-many-attempts	HTTP429 More than 10 checks within one minute from this client address (an IPv6 address counts toward its /64) on this core. The token is not checked. Retry after the Retry-After header (seconds), also given as error.data.retryAfterSeconds.

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.

DNS records are answered before usernames, so a new record under the name of an existing account is refused with 409 item-already-exists (an existing record can still be updated), and a record name cannot be registered as a username.

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.