Textric API Reference

This document defines the public-facing Textric API. Unless otherwise stated, it is assumed that all communication happens over TLS (i.e., HTTPS or WSS for websockets).

In all JSON-formatted payloads, a field ending in ? is optional, and need not be provided. In JSON values, the pipe | indicates a union of types; for example, "hello|world" accepts either "hello" or "world".

User Accounts

The User Account RESTful API handles HTTP requests concerning account management; creation, maintenance, and deletion. Given the private nature of Textric, it should not be surprising that there is little information associated with a user account.

For more information on User Enrollment, see the User Enrollment API

GET /api/users

This endpoint accepts no parameters, and returns a viable user handle. This handle will remain viable for at least five minutes. The client SHOULD NOT cache this; successive calls will return different handles.

Note that the unavailability of a handle DOES NOT imply the existence of said handle; a handle MUST be requested before it can be used.

POST /api/users

This endpoint creates a new user. It accepts a JSON-formatted payload with the following shape:

{
  "handle": "string",
  "password": "string"
}

If the handle is not viable, an HTTP 404 message is sent; upon receiving this code, clients SHOULD discard the given handle. If successful, an account is created and an HTTP 204 response is sent.

PATCH /api/users

This endpoint updates a user's password. It accepts a JSON-formatted payload with the following shape:

{
  "handle": "string",
  "oldPassword": "string",
  "newPassword": "string"
}

If accepted, an HTTP 204 response is sent; otherwise, an HTTP 404 response is sent.

Note that password resets also cause the server to forget all previous devices.

PUT /api/users

This endpoint deletes a user. It accepts a JSON-formatted payload with the following shape:

{
  "handle": "string",
  "hash": "string"
}

Upon success, an HTTP 204 response is sent; otherwise, an HTTP 404 response is sent.

Devices

This API endpoint is responsible for enrolling devices for a given user.

For more information on device enrollment, see the Device Enrollment API.

POST api/devices

This endpoint initiates a request to enroll a device, and accepts a JSON-formatted payload with the following shape:

{
  "handle": "string",
  "deviceID": "string"
}

This will always send back the following payload:

{
  "nonce": "string",
  "hashAlgorithm": "HashAlgorithm",
  "salt": "string"
}

If a user account doesn't exist, a random, yet deterministic, salt will be sent. In this way, there is no way to determine if a user account actually exists from this alone

PUT /api/devices

This endpoint completes a request to enroll a device, and accepts a JSON-formatted payload with the following shape:

{
  "handle": "string",
  "deviceID": "string",
  "hash": "string",
  "info?":
  {
    "name?": "string",
    "os?": "string",
    "type?": "mobile|tablet|desktop|other"
  }
}

Upon failure, an HTTP 401 response is sent; otherwise, an HTTP 200 response is sent, along with a new base-64 encoded nonce.