Comment on page
Endpoints
List of DeSo Identity Window API endpoints
This section describes all endpoints for the Window API.
Endpoints are called with URL parameters, some of which are optional. After the user completes the flow within the window, Identity will send a
postMessage
response.This endpoint is used to handle user login or account creation.
const login = window.open('https://identity.deso.org/log-in');
Name | Type | Description |
---|---|---|
accessLevelRequest (optional) | int | |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
webview (optional) | bool | Whether we're using webview. Default is false |
jumio (optional) | bool | Whether to show "get free deso" during signup. Default is false |
referralCode (optional) | string | Referral Code through which the user accessed the site. The referral code allows the user to get a greater amount of money as a sign-up bonus. Also check outget-free-deso |
hideGoogle (optional) | bool | Hide Google login from the Identity UI. Default is false |
accessLevelRequest
can take values from {0, 2, 3, 4}. You should only ask for the lowest permission that fits the requirements of your application.Here's what each level means:
enum AccessLevel {
// User revoked permissions
None = 0,
// Approval required for all transactions.
// This means no account action is authorized.
ApproveAll = 2, /* DEFAULT */
// Approval required for buys, sends, and sells
// This authorizes all non-spending actions.
ApproveLarge = 3,
// Node can sign all transactions without approval
// This authorizes all non-spending & spending actions.
Full = 4,
}
{
id: null,
service: "identity",
method: "login",
payload: {
users: {
BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX: {
accessLevel: 4,
accessLevelHmac: "0d22e283751c904ab36dc3910afe1a981...",
btcDepositAddress: "1PXhm3D6sgZtfGNe2mtP27NVBHEcNJX2AW",
encryptedSeedHex: "bdad93a19eb3be8b4c2f63b5cefb82823...",
hasExtraText: false,
network: "mainnet",
},
BC1...
},
publicKeyAdded: 'BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX',
signedUp: false,
}
}
For a log in or sign up action, the selected
publicKey
will be included in publicKeyAdded
. When a user signs up the
signedUp
field will be set to true
, otherwise it'll be false
for log in.An application should store the current
publicKeyAdded
and users
objects in its local storage.You should always overwrite the existing, saved users.
When an application wants to sign a transaction or decrypt a message, the
accessLevel
, accessLevelHmac
, and encryptedSeedHex
values will be required.Logout is used to reset the
accessLevel
of an individual user. You should handle user logout by calling this endpoint.When you logout a user, you should delete the corresponding
userCredentials
entry form the local storage/database.const logout = window.open('https://identity.deso.org/logout');
Name | Type | Description |
---|---|---|
publicKey | string | Public key of the user that is logging out |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
webview (optional) | bool | Whether we're using webview. Default is false |
{
id: null,
service: "identity",
method: "login",
payload: {
users: {
BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX: {
accessLevel: 4,
accessLevelHmac: "0d22e283751c904ab36dc3910afe1a981...",
btcDepositAddress: "1PXhm3D6sgZtfGNe2mtP27NVBHEcNJX2AW",
encryptedSeedHex: "bdad93a19eb3be8b4c2f63b5cefb82823...",
hasExtraText: false,
network: "mainnet",
},
BC1...
}
}
}
The approve endpoint is used for transaction signing.
If you're unsure what this means, make sure to check out the Transactions section to see how transactions work in the DeSo blockchain.
Usually, the approve endpoint is called when you want to sign a transaction that's outside the scope of the
accessLevel
you have requested during log-in.For example, if you requested
accessLevel=3
and want to sign a BasicTransfer
transaction (constructed via api/v0/send-deso
Backend API), you would need to use the approve endpoint because BasicTransfer
requires accessLevel=4
.If the transaction you want to sign is within the scope of the
accessLevel
you have, you should sign it through the Identity: iFrame API.const approve = window.open('https://identity.deso.org/approve');
Name | Type | Description |
---|---|---|
tx | string | Transaction hex of the transaction to sign |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
webview (optional) | bool | Whether we're using webview. Default is false |
{
id: null,
service: "identity",
method: "login",
payload: {
users: {
BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX: {
accessLevel: 4,
accessLevelHmac: "0d22e283751c904ab36dc3910afe1a981...",
btcDepositAddress: "1PXhm3D6sgZtfGNe2mtP27NVBHEcNJX2AW",
encryptedSeedHex: "bdad93a19eb3be8b4c2f63b5cefb82823...",
hasExtraText: false,
network: "mainnet",
},
BC1...
},
signedTransactionHex: "0196be9786f1634b2734196bad0798..."
}
}
The derive endpoint is used to generate a derived key for a user.
When you hold a derived key, you can sign transactions for a user without having to interact with the DeSo Identity Service.
In such case, you will receive the payload with
method: "derive"
(opposed to "login"
). More information on derived keys can be found in Derived Keys.After the Transaction Spending Limits fork height hits, derived keys will require authorization of transaction spending limits, which provides granular permissions on transaction type and even more granular permissions on NFTs, Creator Coins, and DAO Coins.
const derive = window.open('https://identity.deso.org/derive');
Name | Type | Description |
---|---|---|
callback (optional) | string | |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
webview (optional) | bool | Whether we're using webview. Default is false |
TransactionSpendingLimit | string | TransactionSpendingLimitResponse as a JSON string. Use encodeURIComponent(JSON.stringify(transactionSpendingLimitResponse)) |
PublicKey | String | Public key (in base 58) for which you want to generate a derived key (Optional) |
DerivedPublicKey | String | Derived key (in base 58) that you want to use instead of allowing identity to generate a new one (Optional) |
{
id: null,
service: "identity",
method: "derive",
payload: {
derivedSeedHex: "40538066039f21f42f0247f49fe4e7d63a9d80528486b02fea37ce3c57886546",
derivedPublicKeyBase58Check: "BC1YLjGYUcpF7HMqmUYNoDaV7Wxc8TYoGhGwmigyEVSCKNAxU9GmikD",
publicKeyBase58Check: "BC1YLj8iwsicimv8ttrPg6rBtizvM7X3KCsiVQwYZKqj6Wj3rT8TD3D",
btcDepositAddress: "Not implemented yet",
ethDepositAddress: "Not implemented yet",
expirationBlock: 91587,
network: "mainnet",
accessSignature: "304502206a612483e970e3494191e5242683b2be8d22ca6e20473e990f50098021099d8b022100f5b011ea683499dee50079ed2497bfbd16461e802e53f956d4c9c6cdaa423f47",
jwt: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mzc5OTQ3NDMsImV4cCI6MTY0MDU4Njc0M30.o74505dYS0qZ5EqSxeYiuSzMCTFRLEToLXmudTtbdk3oYhu80M95qbHX5BjHQw4Bvuh7yz8Hv1u2-leReAaf9Q",
derivedJwt: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mzc5OTQ3NDMsImV4cCI6MTY0MDU4Njc0M30.Nb1IuWgOxrG21NG6zyHMA6M-Mlq2kVrIPVNWAhj49jlaDCqlGQAAEBOl4jlVBC3vNU0S9yyq_8QI5Gmz4Qk1lA"
}
}
The meaning of each of these fields is explained in Derived Keys. In the case of the callback, all these fields will be passed as URL parameters.
Assuming, we've passed
callback=auth://derive
, the payload will be sent as a GET request like this:GET auth://derive?derivedSeedHex=...&derivedPublicKey=...&publicKey=...&
btcDepositAddress=...ðDepositAddress=...&expirationBlock=...&network=...&
accessSignature=...&jwt=...&derivedJwt=...
This endpoint is intended to be used in combination with derived keys.
It allows you to get message encryption/decryption keys, or shared secrets, so that you can read messages without querying Identity (as is traditionally done via Identity: iFrame API).
The
get-shared-secrets
endpoint requires a callback as well as other URL parameters that are used to verify ownership of the derived key.Another required URL parameter is
messagePublicKeys
which are the public keys of messaging parties in CSV format for which we want to fetch shared secrets.The
get-shared-secrets
endpoint allows to fetch multiple shared secrets at once.For example, if the owner of the derived key was public key
A
, and we wanted to read conversations between parties B
,C
,D
(or more) we would set ownerPublicKey=A
and messagePublicKeys=B,C,D
.const secrets = window.open('https://identity.deso.org/get-shared-secrets');
Name | Type | Description |
---|---|---|
callback | string | |
ownerPublicKey | string | Master public key that was used to get the derived key |
derivedPublicKey | string | Derived public key |
JWT | string | JWT signed by the derived key, it's passed as derivedJwt in /derive |
messagePublicKeys | Public keys of users for which we want to fetch shared secrets. | |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
The response is a list of shared secrets in CSV format corresponding to
messagePublicKeys
. The payload will always be sent as a callbacks.GET callback?sharedSecrets=ccf9474d7578658e0c77adb7aea5cc9b61d3bccad5bddddd11e1850dfa4db059,
db7aea5cc9b61d3b..., a11e1850dfa4db059...
The
get-free-deso
endpoint allows for launching the Jumio KYC flow, and if completed successfully, it will end up sending your users free starter DeSo or their referral bonus.const free = window.open('https://identity.deso.org/get-free-deso');
Name | Type | Description |
---|---|---|
public_key | string | Public key of the user to be KYC verified |
referralCode (optional) | string | Referral code to be used in Jumio |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
{
id: null,
service: "identity",
method: "login",
payload: {
users: {
BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX: {
accessLevel: 4,
accessLevelHmac: "0d22e283751c904ab36dc3910afe1a981...",
btcDepositAddress: "1PXhm3D6sgZtfGNe2mtP27NVBHEcNJX2AW",
encryptedSeedHex: "bdad93a19eb3be8b4c2f63b5cefb82823...",
hasExtraText: false,
network: "mainnet",
},
BC1...
},
publicKeyAdded: "BC1...",
signedUp: true,
jumioSuccess: true
}
}
The
signedUp
boolean variable determines if the user has logged in or signed up, and jumioSuccess
indicates if the Jumio KYC was successful.The
verify-phone-number
endpoint will give the user some starter DeSo after a successful phone verification.const phone = window.open('https://identity.deso.org/verify-phone-number');
Name | Type | Description |
---|---|---|
public_key | string | Public key of the user to be phone verified |
testnet (optional) | bool | Whether we're on testnet or mainnet. Default is false |
{
id: null,
service: "identity",
method: "login",
payload: {
users: {
BC1YLfsWMfv8UdytwrWqWvqSP6M6eQJg7W5TWL1WNDYd7zxi6wEShQX: {
accessLevel: 4,
accessLevelHmac: "0d22e283751c904ab36dc3910afe1a981...",
btcDepositAddress: "1PXhm3D6sgZtfGNe2mtP27NVBHEcNJX2AW",
encryptedSeedHex: "bdad93a19eb3be8b4c2f63b5cefb82823...",
hasExtraText: false,
network: "mainnet",
},
BC1...
},
publicKeyAdded: "BC1...",
signedUp: true,
phoneNumberSuccess: true
}
}
The
signedUp
boolean variable determines if the user has logged in or signed up, and phoneNumberSuccess
indicates if the phone verification was successful.Last modified 10mo ago