# Operator

## Create a new instance <a href="#op-create-instance" id="op-create-instance"></a>

`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](#schema-pad-name)            | true     | The ID of the instance chosen by the Operator                   |
| trusteeIds | body | array<[TrusteeId](#schema-trustee-id)> | 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**

```json
{
    "padName": "my-pad-1.0",
    "trusteeIds": ["trustee1", "trustee2", "trustee3"],
    "t": 2,
}
```

### Responses

| Status | Meaning                                                                 | Description                                                                        | Schema                              |
| ------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------- |
| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)            | Succeeded                                                                          | [ApiResponse](#schema-api-response) |
| 400    | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)        | Invalid instance ID, non-existing trustee or invalid trustee threshold is provided | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)         | API key is missing or invalid                                                      | [ApiResponse](#schema-api-response) |
| 403    | [Forbidden](https://tools.ietf.org/html/rfc7235#section-6.5.3)          | User does not have permission for this request                                     | [ApiResponse](#schema-api-response) |
| 409    | [Conflict](https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8) | Instance with the same name already exists                                         | [ApiResponse](#schema-api-response) |

#### 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**

```json
{
    "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](#schema-pad-name) for details.
* All the trustee IDs are valid. Check out [this endpoint](#op-get-trustee-universe) 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**

```json
{
  "ok": false,
  "message": "The trustee trustee4 does not exist",
}
```

**Example2**

```json
{
  "ok": false,
  "message": "invalid value at body.t. Expected: <= 3; given: 4",
}
```

#### 401 Unauthorized

Api key is missing or invalid.

**Example**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

#### 403 Forbidden

User does not have permission to make this request.

**Example**

```json
{
  "ok": false,
  "message": "Forbidden",
}
```

#### 409 Conflict

A PAD instance of the same name already existed.

**Example**

```json
{
  "ok": false,
  "message": "the instance has already been created",
}
```

## Get the Trustee universe <a href="#op-get-trustee-universe" id="op-get-trustee-universe"></a>

`GET /all-trustees`

### Description

Retrieve all the registered Trustees - their IDs, descriptive names and public keys.

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved the Trustees.

**Schema**

| Name            | Type                                                             | Required | Restrictions | Description |
| --------------- | ---------------------------------------------------------------- | -------- | ------------ | ----------- |
| ok              | boolean                                                          | true     | none         | none        |
| trusteeUniverse | dict<[TrusteeId](#schema-trustee-id),[Trustee](#schema-trustee)> | true     | none         | none        |

**Example**

```json
{
  "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**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

**Example**

## Get the Validator universe <a href="#op-get-validator-universe" id="op-get-validator-universe"></a>

`GET /all-validators`

### Description

Retrieve all the registered Validators - their IDs, descriptive names and public keys.

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved the Validators.

**Schema**

| Name              | Type                                                                     | Required | Restrictions | Description |
| ----------------- | ------------------------------------------------------------------------ | -------- | ------------ | ----------- |
| ok                | boolean                                                                  | true     | none         | none        |
| validatorUniverse | dict<[ValidatorId](#schema-validator-id),[Validator](#schema-validator)> | true     | none         | none        |

**Example**

```json
{
  "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**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

## Schemas

### PadName <a href="#schema-pad-name" id="schema-pad-name"></a>

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**

```json
"my-pad-1.0"
```

#### Schema

| Type   | Restrictions              |
| ------ | ------------------------- |
| string | `/[a-z][a-z0-9.-]{3,29}/` |

### TrusteeId <a href="#schema-trustee-id" id="schema-trustee-id"></a>

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 <a href="#schema-trustee" id="schema-trustee"></a>

An object listing details of a trustee, including its ID, human-readable description/name, its role (`Trustee`) and its public keys.

**Example**

```json
{
  "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](#schema-trustee-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 <a href="#schema-validator" id="schema-validator"></a>

An object listing details of a validator, including its ID, human-readable description/name, its role (`Validator`) and its public keys.

**Example**

```json
{
  "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](#schema-validator-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 <a href="#schema-api-response" id="schema-api-response"></a>

**Example**

```json
{
  "ok": true,
  "message": "string"
}
```

#### Schema

| Name    | Type    | Required | Description                      |
| ------- | ------- | -------- | -------------------------------- |
| ok      | boolean | true     | The request is successful or not |
| message | string  | true     | none                             |