# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.photonsdk.org/key-server-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.