openapi: 3.0.0 info: description: Description of Pryv.io System API in Open API 3.0 standard format version: 2.0.0-pre title: Pryv.io System API contact: url: https://github.com/pryv/open-pryv.io/issues license: name: MIT url: https://opensource.org/licenses/MIT paths: /admin/users: get: description: Get the list of all users registered on the platform. operationId: users.get parameters: - name: toHTML description: If `true`, format the resulting users list as HTML tables. required: false in: query responses: "200": content: application/json: schema: - type: array /admin/servers: get: description: Get the list of all core servers with the number of users on them. operationId: servers.get responses: "200": content: application/json: schema: - type: object "/admin/servers/{serverName}/users": get: description: Get the list of all users registered on a specific core server. operationId: servers.users.get parameters: - name: serverName description: The name of the core server. required: true in: query - name: serverName responses: "200": content: application/json: schema: - type: array "/admin/servers/{srcServerName}/rename/{dstServerName}": get: description: Rename a core server, thus reassigning the users from srcServer to dstServer. operationId: servers.rename parameters: - name: srcServerName description: The current name of the core server to rename. required: true in: query - name: dstServerName description: The new name of the core server. required: true in: query - name: srcServerName - name: dstServerName responses: "200": content: application/json: schema: - type: number "400": description: INVALID_DATA /hostings: get: description: Get the list of all available hostings for data storage locations. operationId: hostings.get responses: "200": content: application/json: schema: - type: Object /apps: get: description: Retrieve the list of applications connected to the platform. operationId: apps.get responses: "200": content: application/json: schema: - type: array "/apps/{appid}": get: description: Retrieve information about a given application. operationId: apps.getOne parameters: - name: appid description: The id of the application to look for. required: true in: query - name: appid responses: "200": content: application/json: schema: - type: object /users: post: description: >- Creates a new user account. The method's parameters can be customized with the [system streams configuration](/customer-resources/system-streams/). 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` operationId: users.create responses: "200": content: application/json: schema: - type: string - type: string "400": description: invalid-parameters-format requestBody: content: application/json: schema: type: object properties: appId: description: Your app's unique identifier. type: string username: description: The user's username. type: string password: description: The user's password. type: string email: description: The user's e-mail address, used for password retrieval. type: string invitationToken: description: > 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. type: string language: description: The user's preferred language as a 2-letter ISO language code. type: string referer: description: A referer id potentially used for analytics. type: string "/{username}/check_username": get: description: >- For the single node mode please use [this](/reference/#check-username) API endpoint. Check the availability and validity of a given username. operationId: username.check parameters: - name: username description: The username to check. required: true in: query - name: username responses: "200": content: application/json: schema: - type: boolean - type: string "400": description: INVALID_USERNAME "/{email}/check_email": get: description: Check the existence of an account's email. operationId: emails.check parameters: - name: email description: The email address to check. required: true in: query - name: email responses: "200": content: application/json: schema: - type: boolean "400": description: INVALID_EMAIL "/{email}/username": get: description: >- Get the username of a Pryv.io account according to the given email. This API method can be disabled in the [platform configuration](https://pryv.github.io/reference-admin/#platform-settings). 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": "" }` 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. operationId: email.username.get parameters: - name: email description: The email address to look for. required: true in: query - name: email responses: "200": content: application/json: schema: - type: string "404": description: UNKNOWN_EMAIL /cores: get: description: Get the core of a Pryv.io account according to the given username or email. You must provide **only** one of them. operationId: cores.get parameters: - name: username description: The username to look for. required: true in: query - name: email description: >- 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. required: true in: query responses: "200": content: application/json: schema: - type: object "/users/{username}": delete: description: >- 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](#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](/reference-admin/#delete-user). - For Open Pryv.io users, this method requires to provide the [auth:adminAccessKey](https://github.com/pryv/open-pryv.io#config) as `Authorization` header. operationId: users.delete parameters: - name: username description: The username of the account to delete. required: true in: query - name: username responses: "200": content: application/json: schema: - type: object /reg/access: post: description: >- 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. operationId: access.create responses: "201": content: application/json: schema: - type: string - type: string - type: string - type: number requestBody: content: application/json: schema: type: object properties: requestingAppId: description: The id of the app requesting access. type: string requestedPermissions: description: The permissions requested by the app. type: array of permission objects returnURL: description: An optional URL to redirect the user to after accepting or refusing. type: string clientData: description: Optional metadata the requesting app wants to attach to the request. type: object "/reg/access/{key}": get: description: >- 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`. operationId: access.poll parameters: - name: key description: The polling key returned by [Create access request](#create-access-request). required: true in: query - name: key responses: "200": content: application/json: schema: - type: string - type: string - type: string - type: string post: description: >- Updates the state of an access request. Called by the auth page after the user has signed in and accepted or refused the permissions. operationId: access.update parameters: - name: key responses: "200": content: application/json: schema: - type: string requestBody: content: application/json: schema: type: object properties: status: description: "The new status: `ACCEPTED`, `REFUSED`, `ERROR`, or `REDIRECTED`." type: string username: description: (Required when `ACCEPTED`) The username granting the access. type: string token: description: (Required when `ACCEPTED`) The token for the access. type: string /access/invitationtoken/check: post: description: >- 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. operationId: invitationtoken.check responses: "200": content: application/json: schema: - type: string requestBody: content: application/json: schema: type: object properties: invitationtoken: description: The invitation token to verify. type: string /reg/admin/invitations: get: description: Lists all invitation tokens configured on the platform. Requires admin authorization. operationId: invitations.list responses: "200": content: application/json: schema: - type: array /reg/admin/invitations/post: get: description: Generates new invitation tokens. Requires admin authorization. operationId: invitations.generate parameters: - name: count description: "Number of tokens to generate (default: 1)." required: true in: query - name: message description: Optional description for the generated tokens. required: false in: query responses: "200": content: application/json: schema: - type: object /reg/records: post: description: >- 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. operationId: dns.records responses: "200": content: application/json: schema: - type: string - type: string requestBody: content: application/json: schema: type: object properties: subdomain: description: The subdomain to set records for. type: string records: description: 'The DNS records to set (e.g. `{ "TXT": "challenge-value" }`).' type: object components: schemas: {}