Operator

Create a new instance
POST /PADs
Description
Operator creates an instance. The request body consists of the Operator's choice of the instance name, the list of trustees referencing the instance, and the corresponding threshold. All validators will be nominated automatically, with a threshold ⌊#validators/2⌋+1\lfloor\#\mathrm{validators}/2\rfloor + 1⌊#validators/2⌋+1
. This endpoint also binds the API key to the instance, i.e. the API key can only access endpoints associated to the created instance afterwards.
Choose the parameters carefully. They cannot be changed once the instance is created.
The instance is not fully functional after creation. It takes time for the trustees and validators to realise this change. They may choose not to serve this instance as well.
Parameters
Name
In
Type
Required
Description
padName
body
​PadName​
true
The ID of the instance chosen by the Operator
trusteeIds
body
array<TrusteeId>
true
The IDs of the trustees nominated by the Operator
t
body
integer
true
The minimum number of trustee responses needed for a decryption
Example
{
    "padName": "my-pad-1.0",
    "trusteeIds": ["trustee1", "trustee2", "trustee3"],
    "t": 2,
}
Responses
Status
Meaning
Description
Schema
201
​Created​
Succeeded
​ApiResponse​
400
​Bad Request​
Invalid instance ID, non-existing trustee or invalid trustee threshold is provided
​ApiResponse​
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
403
​Forbidden​
User does not have permission for this request
​ApiResponse​
409
​Conflict​
Instance with the same name already exists
​ApiResponse​
201 Created
The instance is successfully created. This response is returned after the instance is created. The creation process could take up to 30 seconds.
Example
{
    "ok": true,
    "message": "Successfully created PAD instance",
}
400 Bad Request
The request is malformed. Check that:
The PAD instance name is valid. See the PadName schema for details.
All the trustee IDs are valid. Check out this endpoint which retrieves all the registered trustees.
The trustee threshold is valid. It should be a positive integer at most the number of trustees nominated.
Example1
{
  "ok": false,
  "message": "The trustee trustee4 does not exist",
}
Example2
{
  "ok": false,
  "message": "invalid value at body.t. Expected: <= 3; given: 4",
}
401 Unauthorized
Api key is missing or invalid.
Example
{
  "ok": false,
  "message": "Unauthorized",
}
403 Forbidden
User does not have permission to make this request.
Example
{
  "ok": false,
  "message": "Forbidden",
}
409 Conflict
A PAD instance of the same name already existed.
Example
{
  "ok": false,
  "message": "the instance has already been created",
}
Get the Trustee universe
GET /all-trustees
Description
Retrieve all the registered Trustees - their IDs, descriptive names and public keys.
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
200 OK
Successfully retrieved the Trustees.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
trusteeUniverse
dict<TrusteeId,Trustee>
true
none
none
Example
{
  "ok": true,
  "trusteeUniverse": {
    "trustee1": {
      "id": "trustee1",
      "fullName": "Trustee-1",
      "role": "Trustee",
      "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----",
      "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
      },
    },
  },
}
401 Unauthorized
Api key is missing or invalid.
Example
{
  "ok": false,
  "message": "Unauthorized",
}
Example
Get the Validator universe
GET /all-validators
Description
Retrieve all the registered Validators - their IDs, descriptive names and public keys.
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
200 OK
Successfully retrieved the Validators.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
validatorUniverse
dict<ValidatorId,Validator>
true
none
none
Example
{
  "ok": true,
  "validatorUniverse": {
    "validator1": {
      "id": "validator1",
      "fullName": "Validator-1",
      "role": "Validator",
      "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----",
      "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
      },
    },
  },
}
401 Unauthorized
Api key is missing or invalid.
Example
{
  "ok": false,
  "message": "Unauthorized",
}
Schemas
PadName
ID of a PAD instance. Its length must be inclusively between 4 and 30. It should contains only lowercase letters, digits, periods (.) or dashes (-). It must start with a lowercase letter.
It is seldom used as a request parameter because the API key in the request already identifies a PAD instance.
Example
"my-pad-1.0"
Schema
Type
Restrictions
string
/[a-z][a-z0-9.-]{3,29}/
TrusteeId
ID of a trustee. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
trustee1
Schema
Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}
Trustee
An object listing details of a trustee, including its ID, human-readable description/name, its role (Trustee) and its public keys.
Example
{
  "id": "trustee1",
  "fullName": "Trustee-1",
  "role": "Trustee",
  "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----\n",
  "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----"
}
Schema
Name
Type
Required
Restrictions
Description
id
​TrusteeId​
true
/[0-9a-zA-Z-_]{3,30}/
none
fullName
string
true
/Trustee-[0-9a-zA-Z_]+/
none
role
enum
true
none
none
encryptionKey
string
true
none
PEM-encoded (public) encryption key of the trustee. Used by encryptors at encryption time
verificationKey
string
true
none
PEM-encoded (public) verification key of trustee
Validator
An object listing details of a validator, including its ID, human-readable description/name, its role (Validator) and its public keys.
Example
{
  "id": "validator1",
  "fullName": "Validator1",
  "role": "Validator",
  "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----\n",
  "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----"
}
Schema
Name
Type
Required
Restrictions
Description
id
​ValidatorId​
true
-
none
fullName
string
true
/Validator-[0-9a-zA-Z_]+/
none
role
enum
true
none
none
encryptionKey
string
true
none
PEM-encoded (public) encryption key of the validator. Used by encryptors at encryption time
verificationKey
string
true
none
PEM-encoded (public) verification key of validator
ApiResponse
Example
{
  "ok": true,
  "message": "string"
}
Schema
Name
Type
Required
Description
ok
boolean
true
The request is successful or not
message
string
true
none