Key Server API

A documentation of the REST api for the Photon key server used for encrypted cloud backup of the user's wallet seed.

Create Key

POST 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)

201 Returns the key ID which the client needs to store.

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

400 If the PIN was invalid or too short.

{
  "message": "Invalid request"
}

Get Key

GET 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

200 Key successfully retrieved.

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

404 Could not find a key matching this query.

{
  "message": "Invalid request"
}

Change PIN

PUT 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)

200 PIN successfully changed.

{
  "message": "Success"
}

Create User

POST 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

201

{
  "message": "Success"
}

Verify User

PUT 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

200 User verification was successful

{
  "message": "Success"
}

404 The code or user ID was invalid.

{
  "message": "Invalid params"
}

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"
}

Reset PIN

GET 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

200

{
  "message": "Success"
}

Remove User

DELETE 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

200 The user ID was deleted from the server

{
  "message": "Success"
}

400 The PIN or path params were incorrect

{
  "message": "Invalid request"
}