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 $\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	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