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

NameInTypeRequiredDescription

padName

body

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

StatusMeaningDescriptionSchema

201

Succeeded

400

Invalid instance ID, non-existing trustee or invalid trustee threshold is provided

401

API key is missing or invalid

403

User does not have permission for this request

409

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

StatusMeaningDescriptionSchema

200

Succeeded

Inline

401

API key is missing or invalid

200 OK

Successfully retrieved the Trustees.

Schema

NameTypeRequiredRestrictionsDescription

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

StatusMeaningDescriptionSchema

200

Succeeded

Inline

401

API key is missing or invalid

200 OK

Successfully retrieved the Validators.

Schema

NameTypeRequiredRestrictionsDescription

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

TypeRestrictions

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

TypeRestrictions

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

NameTypeRequiredRestrictionsDescription

id

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

NameTypeRequiredRestrictionsDescription

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

NameTypeRequiredDescription

ok

boolean

true

The request is successful or not

message

string

true

none

Last updated