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
. 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
400
Invalid instance ID, non-existing trustee or invalid trustee threshold is provided
401
API key is missing or invalid
403
Forbidden
User does not have permission for this request
409
Conflict
Instance with the same name already exists

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
API key is missing or invalid

200 OK

Successfully retrieved the Trustees.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
trusteeUniverse
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
API key is missing or invalid

200 OK

Successfully retrieved the Validators.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
validatorUniverse
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
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