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.
postCreate 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
Response
Request
Body Parameters
pin
required
string
A PIN required for authentication (at least 4 digits)
Response
201: Created
Returns the key ID which the client needs to store.
{"id": "36e6b967-eeeb-4b54-818b-13331416c9f4"}
400: Bad Request
If the PIN was invalid or too short.
{"message": "Invalid request"}
getGet Key
get
https://keys-dev.photonsdk.com/v2/key/:keyId
Fetch the encryption key from the api endpoint.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
Headers
Authorization
required
string
Basic Authentication as a base64 encoded PIN in a user:pass pair
Response
200: OK
Key successfully retrieved.
{"id": "36e6b967-eeeb-4b54-818b-13331416c9f4","encryptionKey": "kjXCstWMW3ed3zBTU3sDg/XyPxPkbaz3yVfB9bP+w7A="}
404: Not Found
Could not find a key matching this query.
{"message": "Invalid request"}
putChange PIN
put
https://keys-dev.photonsdk.com/v2/key/:keyId
Change the PIN used for authenticating encryption key operations.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
Headers
Authorization
required
string
Basic Authentication as a base64 encoded PIN in a user:pass pair
Body Parameters
newPin
required
string
The new PIN (at least 4 digits)
Response
200: OK
PIN successfully changed.
{"message": "Success"}
postCreate 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.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
Headers
Authorization
required
string
Basic Authentication as a base64 encoded PIN in a user:pass pair
Body Parameters
userId
required
string
An email address or phone number
Response
201: Created
{"message": "Success"}
putVerify 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.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
userId
required
string
Email address or phone number
Body Parameters
op
required
string
Verify operation: "verify" or "reset-pin"
code
required
string
Verification code sent via email or sms
newPin
optional
string
The new PIN to be set after a PIN reset
Response
200: OK
User verification was successful
{"message": "Success"}
404: Not Found
The code or user ID was invalid.
{"message": "Invalid params"}
423: Locked
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"}
getReset 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.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
userId
required
string
Email address or phone number
Response
200: OK
{"message": "Success"}
deleteRemove 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.
Request
Response
Request
Path Parameters
keyId
required
string
ID of the key
userId
required
string
Email address or phone number
Headers
Authorization
required
string
Basic Authentication as a base64 encoded PIN in a user:pass pair
Response
200: OK
The user ID was deleted from the server
{"message": "Success"}
400: Bad Request
The PIN or path params were incorrect
{"message": "Invalid request"}
Last updated 6 months ago