Endpoints
List of DeSo Identity iframe API endpoints
Note:
The iframe API supports functionality for both public keys and derived keys. You can determine key type from the login response by checking for derivedPublicKeyBase58Check
.
sign
AccessLevel: 3, 4 (depends on transaction)
The sign message is responsible for signing transaction hexes. If approval is required an application must call the #approve endpoint in the Window API to sign the transaction.
Payload for public keys
Name | Type | Description |
---|---|---|
transactionHex | string | Hex of the transaction you want to sign. |
Payload for derived keys
Name | Type | Description |
---|---|---|
transactionHex | string | Hex of the transaction you want to sign. |
derivedPublicKeyBase58Check | string | Only required if logged in user is using a derived key to sign on behalf of an owner public key. |
Request
Response (Success)
You will get this response if the transaction was successful signed.
Response (Approval Required)
You will get this response if the accessLevel
your user has authorized doesn't match the access level required to sign a transaction.
encrypt
AccessLevel: 2
Payload for public keys
Name | Type | Description |
---|---|---|
recipientPublicKey | string | Public key of the recipient in base58check format. |
message | string | Message text that you want to encrypt. |
Payload for derived keys
Only required if logged in user is using a derived key to sign on behalf of an owner public key.
recipientPublicKey | string | Public key of the recipient in base58check format. |
message | string | Message text that you want to encrypt. |
encryptedMessagingKeyRandomness | string | This value is used in place of the |
derivedPublicKeyBase58Check | string | Public key requesting encryption in base58check format. |
ownerPublicKeyBase58Check | string | Public key used only for validation. |
Request
Response for Derived keys (Encrypted Messaging Key Randomness Required)
You will get this response if the request includes a derivedPublicKeyBase58Check
and does not include both ownerPublicKeyBase58Check
and encryptedMessagingKeyRandomness
.
You can request Encrypted MessagingKeyRandomness by calling the messaging-group in the Window API.
Response (Approval Required)
You will get this response if the accessLevel
your user has authorized doesn't match the access level required to sign a transaction.
To fix, the user needs to allow at least access level 2.
Response
decrypt
AccessLevel: 2
The decrypt API is responsible for decrypting messages.
The decrypt API allows you to decrypt multiple messages at once by passing an array of encryptedMessage
objects.
The decrypt
API is intended to be constructed right after calling the /api/v0/get-messages-stateless
backend API endpoint, and so the structure of encryptedMessage
matches the structure of the response from backend.
We recommend tracing through GetMessages()
function in the DeSo Protocol frontend's src/app/backend-api.service.ts
.
Assuming message
is a taken from OrderedContactsWithMessages.Messages
from the backend API response, encryptedMessage
can be constructed as follows:
Another use-case for the decrypt
API is decrypting unlock-able text in NFTs.
To see how this can be done, we recommend tracing through the DecryptUnlockableTexts()
in the DeSo Protocol repository.
Payload for public keys
Name | Type | Description |
---|---|---|
encryptedMessages | []encryptedMessage | List of encrypted messages objects. |
Payload for derived keys
derivedPublicKeyBase58Check | string | Public key requesting decryption in base58check format. |
ownerPublicKeyBase58Check | string | Used to identify which messaging group member entry is used to decrypt group messages. |
encryptedMessagingKeyRandomness | string | Required to decrypt the request. |
encryptedMessages | []encryptedMessage | List of encrypted messages objects. |
Request
Response (Encrypted Messaging Key Randomness Required)
You will get this response if the request includes a derivedPublicKeyBase58Check
and does not include both ownerPublicKeyBase58Check
and encryptedMessagingKeyRandomness
.
Response (Approval Required)
You will get this response if the accessLevel
your user has authorized doesn't match the access level required to sign a transaction.
To fix, the user needs to allow at least access level 2.
Response
Response contains a decryptedHexes
field which is a map of decrypted messages, indexed by EncryptedHex
from the request.
jwt
AccessLevel: 2
The jwt
message creates signed JWT tokens that can be used to verify a user's ownership of a specific public key.
The JWT is only valid for 10 minutes.
JWTs are used in some Backend API endpoints such as /api/v0/upload-image.
The best practice is to request the JWT right before calling these endpoints.
Payload for public keys
Name | Type | Description |
---|---|---|
N/A | N/A | No payload. |
payload for derived keys
Name | Type | Description |
---|---|---|
derivedPublicKeyBase58Check | string | Informs Identity on how to sign the transaction. |
Request
Response
Validation in Go
In case you want to validate the JWT token in Go, you could use the code below:
Last updated