# Key Server API

## Create Key

<mark style="color:green;">`POST`</mark> `https://keys-dev.photonsdk.com/v2/key`

Create a new encryption key e.g. when a new user registers to backup their data during app sign up.

#### Request Body

| Name | Type   | Description                                           |
| ---- | ------ | ----------------------------------------------------- |
| pin  | string | A PIN required for authentication (at least 4 digits) |

{% tabs %}
{% tab title="201 Returns the key ID which the client needs to store." %}

```
{
  "id": "36e6b967-eeeb-4b54-818b-13331416c9f4"
}
```

{% endtab %}

{% tab title="400 If the PIN was invalid or too short." %}

```
{
  "message": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Get Key

<mark style="color:blue;">`GET`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId`

Fetch the encryption key from the api endpoint.

#### Path Parameters

| Name  | Type   | Description   |
| ----- | ------ | ------------- |
| keyId | string | ID of the key |

#### Headers

| Name          | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| Authorization | string | Basic Authentication as a base64 encoded PIN in a **user:pass** pair |

{% tabs %}
{% tab title="200 Key successfully retrieved." %}

```
{
  "id": "36e6b967-eeeb-4b54-818b-13331416c9f4",
  "encryptionKey": "kjXCstWMW3ed3zBTU3sDg/XyPxPkbaz3yVfB9bP+w7A="
}
```

{% endtab %}

{% tab title="404 Could not find a key matching this query." %}

```
{
  "message": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Change PIN

<mark style="color:orange;">`PUT`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId`

Change the PIN used for authenticating encryption key operations.

#### Path Parameters

| Name  | Type   | Description   |
| ----- | ------ | ------------- |
| keyId | string | ID of the key |

#### Headers

| Name          | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| Authorization | string | Basic Authentication as a base64 encoded PIN in a **user:pass** pair |

#### Request Body

| Name   | Type   | Description                     |
| ------ | ------ | ------------------------------- |
| newPin | string | The new PIN (at least 4 digits) |

{% tabs %}
{% tab title="200 PIN successfully changed." %}

```
{
  "message": "Success"
}
```

{% endtab %}
{% endtabs %}

## Create User

<mark style="color:green;">`POST`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId/user`

Create a new user for the key. A user can be identified either by email address or phone number.

#### Path Parameters

| Name  | Type   | Description   |
| ----- | ------ | ------------- |
| keyId | string | ID of the key |

#### Headers

| Name          | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| Authorization | string | Basic Authentication as a base64 encoded PIN in a **user:pass** pair |

#### Request Body

| Name   | Type   | Description                      |
| ------ | ------ | -------------------------------- |
| userId | string | An email address or phone number |

{% tabs %}
{% tab title="201 " %}

```
{
  "message": "Success"
}
```

{% endtab %}
{% endtabs %}

## Verify User

<mark style="color:orange;">`PUT`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId/user/:userId`

Verify a new user via the code sent via email or sms (op = "verify"). This api endpoint is also called to verify a PIN reset (op = "reset-pin"). In order to mitigate a SIM swap attack the PIN reset must be verified twice with a 30 day time delay in between.

#### Path Parameters

| Name   | Type   | Description                   |
| ------ | ------ | ----------------------------- |
| keyId  | string | ID of the key                 |
| userId | string | Email address or phone number |

#### Request Body

| Name   | Type   | Description                               |
| ------ | ------ | ----------------------------------------- |
| op     | string | Verify operation: "verify" or "reset-pin" |
| code   | string | Verification code sent via email or sms   |
| newPin | string | The new PIN to be set after a PIN reset   |

{% tabs %}
{% tab title="200 User verification was successful" %}

```
{
  "message": "Success"
}
```

{% endtab %}

{% tab title="404 The code or user ID was invalid." %}

```
{
  "message": "Invalid params"
}
```

{% endtab %}

{% tab title="423 PIN reset was successfully verified with the correct code. A second PIN reset can now be done once the security time delay is over to mitigate a SIM swap attack." %}

```
{
  "message": "Time locked until",
  "delay": "2020-12-16T13:56:45.848Z"
}
```

{% endtab %}
{% endtabs %}

## Reset PIN

<mark style="color:blue;">`GET`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId/user/:userId/reset`

Initiate a PIN reset for the key. A verification code will be sent to the provided email address or phone number.

#### Path Parameters

| Name   | Type   | Description                   |
| ------ | ------ | ----------------------------- |
| keyId  | string | ID of the key                 |
| userId | string | Email address or phone number |

{% tabs %}
{% tab title="200 " %}

```
{
  "message": "Success"
}
```

{% endtab %}
{% endtabs %}

## Remove User

<mark style="color:red;">`DELETE`</mark> `https://keys-dev.photonsdk.com/v2/key/:keyId/user/:userId`

Delete an email address or phone number that is associated with a key.

#### Path Parameters

| Name   | Type   | Description                   |
| ------ | ------ | ----------------------------- |
| keyId  | string | ID of the key                 |
| userId | string | Email address or phone number |

#### Headers

| Name          | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| Authorization | string | Basic Authentication as a base64 encoded PIN in a **user:pass** pair |

{% tabs %}
{% tab title="200 The user ID was deleted from the server" %}

```
{
  "message": "Success"
}
```

{% endtab %}

{% tab title="400 The PIN or path params were incorrect" %}

```
{
  "message": "Invalid request"
}
```

{% endtab %}
{% endtabs %}