Identity Keys
Identity Keys are used to verify blockchain account ownership and validating peer to peer requests are legitimate without requiring the wallet user to sign every message with their blockchain private key. By the blockchain account signing a CAIP-122 message that includes the Identity Key's public key, it authorizes the Identity Key to sign messages on behalf of the blockchain account.
Keys
Identity Keys are randomly generated ed25519 key pairs that are unique per client/device per blockchain account.
If the wallet user uses multiple devices, each device SHOULD use a different identity key.
If the wallet user has multiple blockchain accounts, each account MAY use a separate identity key.
Key Authorization
Identity Keys are authorized by a blockchain account by the wallet user signing a CAIP-122 message with includes the public key of the Identity Key as the URI.
Below is an example CAIP-122 message authorizing the Identity Key with the z6MkqJ6qV18zBazggzhGMHNgadEQGbX9RceEH3j2G6kNTbKq
public key.
app.example.com wants you to sign in with your Ethereum account:
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
I further authorize this app to send me notifications. Read more at https://walletconnect.com/notifications
URI: did:key:z6MkqJ6qV18zBazggzhGMHNgadEQGbX9RceEH3j2G6kNTbKq
Version: 1
Chain ID: 1
Nonce: bb0b6514e8a5e817
Issued At: 2023-09-01T15:29:36.509Z
Resources:
- https://keys.walletconnect.com
The important components from this message are as follows:
domain
-app.example.com
address
-0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
Identity Key public key
-z6MkqJ6qV18zBazggzhGMHNgadEQGbX9RceEH3j2G6kNTbKq
statement
-I further authorize this app to send me notifications. Read more at https://walletconnect.com/notifications
Authorization levels
In the above example, "limited authorization" was used. Various forms of authorization are supported to enable various use cases, and to ensure that the user ultimately decides what permission an app has over their notifications. The statement
decides the authorization level.
Limited statement
Limited authorization allows the app to only access messages for domain
.
I further authorize this app to send me notifications. Read more at https://walletconnect.com/notifications
Unlimited statement
Unlimited authorization allows the app to access messages, regardless of domain
.
I further authorize this app to view and manage my notifications for ALL apps. Read more at https://walletconnect.com/notifications-all-apps
CACAO Format
The CACAO is a standard JSON representation of a signed CAIP-122 message. For example:
{
"h": {
"t": "eip4361"
},
"p": {
"aud": "did:key:z6MkqJ6qV18zBazggzhGMHNgadEQGbX9RceEH3j2G6kNTbKq",
"iat": "2023-09-01T17:09:21.481+03:00",
"statement" : "I further authorize this app to view and manage my notifications for ALL apps. Read more at https://walletconnect.com/notifications-all-apps",
"iss": "did:pkh:eip155:1:0xBAc675C310721717Cd4A37F6cbeA1F081b1C2a07",
"nonce": "bb0b6514e8a5e817",
"domain": "app.example.com",
"version": "1",
"resources": ["https://keys.walletconnect.com"],
},
"s": {
"s": "5ccb134ad3d874cbb40a32b399549cd32c953dc5dc87dc64624a3e3dc0684d7d4833043dd7e9f4a6894853f8dc555f97bc7e3c7dd3fcc66409eb982bff3a44671b",
"t": "eip191"
}
}
Key Registration
When two clients are using a peer to peer API for some requests they need to verify each others Identity Keys. Therefore we use the Keys Server to index these keys privately and the counter-party can validate that the key would be used for the corresponding account in the WalletConnect identities.
POST /identity
Body
{
"cacao": Cacao
}
Example
POST https://keys.walletconnect.com/identity
Body
{
"cacao": {
"h": { ... },
"p": { ... },
"s": { ... }
}
}
Resolve Identity Key
Used to get a CACAO matching an Identity Key.
GET /identity
Query Params
{
"publicKey": string,
}
ResolveIdentityKeyResponse
{
"cacao": Cacao
}
Response
{
"status": String,
"error": ResponseError?,
"value": ResolveIdentityKeyResponse?
}
Example
GET https://keys.walletconnect.com/identity?publicKey=z6MkkKzGDpQv4mR8Gkamt1Wbsrz4mFjjQpAgDFGE919vH7Ts
Success Response
{
"status": "SUCCESS",
"error": null,
"value": {
"cacao": {
"h": { ... },
"p": { ... },
"s": { ... }
}
}
}
Failure Response
{
"status": "FAILURE",
"error": {
"name": "Identity key not found",
"message": "Cannot find Identity key with specified identifier z6MkkKzGDpQv4mR8Gkamt1Wbsrz4mFjjQpAgDFGE919vH7Ts"
},
"value": null
}
Remove Identity Key
Used to remove an Identity Key from the server
DELETE /identity
Body
{
"idAuth": string
}
IdAuth
The idAuth
is a JWT signed by the Identity Key with the following claims:
- iat - timestamp when JWT was issued
- exp - timestamp when JWT must expire
- iss - public Identity Key in form of did:key
- aud - key server URL used for registering
- pkh - corresponding blockchain account (did:pkh)
- act - description of action intent. Must be equal to "unregister_identity"
Example
DELETE https://keys.walletconnect.com/identity
Body
{
"idAuth": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkaWQ6a2V5Ono2TWtoQk5tQXZ0VDNxeW5YekVCcmlSa2o4TWJoTURxMUs1aFhpY1BTSlZTWnBzOSIsImF1ZCI6Imh0dHA6Ly8xMC4wLjIuMjo4MDgwIiwiaWF0IjoxNjc3MTg4NzU1MjUwLCJleHAiOjE2Nzk3ODA3NTUyNTAsInBraCI6ImRpZDpwa2g6ZWlwMTU1OjE6MHhiYjU0NjZkODcyZGQxN2Y4MDRkMjYwNDVhMWVkMDk3ZWQ4NDM2MmI3In0.cTqEuxARCPwewx4PqhUiG8BkerqGX18icRhMJr9PPQW8fFTqKgjV7D2vzjKcxAEUWY2BL4b2998V0jEASSEIAQ"
}
Data structures
ResponseError
{
"name": String,
"message": String
}