0
# Authentication & Authorization
1

2
Authentication flows and authorization types including CACAO (Chain Agnostic CApability Object) support, session authentication mechanisms, and JSON-RPC method definitions for WalletConnect Protocol.
3

4
## Capabilities
5

6
### Authentication Interface
7

8
Main authentication interface providing stores for keys, topics, and authentication requests.
9

10
```typescript { .api }
11
/**
12
 * Authentication interface with stores for keys, topics, and requests
13
 * Manages authentication flows and CACAO handling
14
 */
15
type IAuth = {
16
  /** Authentication key store */
17
  authKeys: IStore;
18
  /** Pairing topic store */ 
19
  pairingTopics: IStore;
20
  /** Authentication request store */
21
  requests: IStore<AuthTypes.PendingRequest>;
22
};
23
```
24

25
### CACAO (Chain Agnostic CApability Object)
26

27
CACAO structures for blockchain-agnostic authentication and capability verification.
28

29
```typescript { .api }
30
namespace AuthTypes {
31
  /**
32
   * Complete CACAO structure for authentication
33
   */
34
  interface Cacao {
35
    /** CACAO header */
36
    h: CacaoHeader;
37
    /** CACAO payload */
38
    p: CacaoPayload;
39
    /** CACAO signature */
40
    s: CacaoSignature;
41
  }
42

43
  /**
44
   * CACAO header structure
45
   */
46
  interface CacaoHeader {
47
    /** Token type (typically "CAIP-122") */
48
    t: string;
49
  }
50

51
  /**
52
   * CACAO payload structure with authentication details
53
   */
54
  interface CacaoPayload {
55
    /** Domain requesting authentication */
56
    domain: string;
57
    /** Audience (typically the dApp URL) */
58
    aud: string;
59
    /** CACAO version */
60
    version: string;
61
    /** Random nonce for replay protection */
62
    nonce: string;
63
    /** Issued at timestamp (ISO 8601) */
64
    iat: string;
65
    /** Not before timestamp (optional, ISO 8601) */
66
    nbf?: string;
67
    /** Expiration timestamp (optional, ISO 8601) */
68
    exp?: string;
69
    /** Human-readable statement (optional) */
70
    statement?: string;
71
    /** Request ID for tracking (optional) */
72
    requestId?: string;
73
    /** Additional resources (optional) */
74
    resources?: string[];
75
  }
76

77
  /**
78
   * CACAO signature structure
79
   */
80
  interface CacaoSignature {
81
    /** Signature type */
82
    t: string;
83
    /** Signature value */
84
    s: string;
85
    /** Optional signature metadata */
86
    m?: string;
87
  }
88
}
89
```
90

91
### Session Authentication
92

93
Session authentication parameters and request structures for establishing authenticated connections.
94

95
```typescript { .api }
96
namespace AuthTypes {
97
  /**
98
   * Session authentication parameters
99
   */
100
  interface SessionAuthenticateParams {
101
    /** Supported blockchain chains */
102
    chains: string[];
103
    /** Domain requesting authentication */
104
    domain: string;
105
    /** Random nonce for replay protection */
106
    nonce: string;
107
    /** Authentication URI */
108
    uri: string;
109
    /** Not before timestamp (optional) */
110
    nbf?: string;
111
    /** Expiration timestamp (optional) */
112
    exp?: string;
113
    /** Human-readable statement (optional) */
114
    statement?: string;
115
    /** Request ID for tracking (optional) */
116
    requestId?: string;
117
    /** Additional resources (optional) */
118
    resources?: string[];
119
  }
120

121
  /**
122
   * Authentication payload parameters
123
   */
124
  interface PayloadParams {
125
    /** Chain identifier */
126
    chainId: string;
127
    /** Domain requesting authentication */
128
    domain: string;
129
    /** Random nonce */
130
    nonce: string;
131
    /** Authentication URI */
132
    uri: string;
133
    /** Version string */
134
    version: string;
135
    /** Not before timestamp (optional) */
136
    nbf?: string;
137
    /** Expiration timestamp (optional) */
138
    exp?: string;
139
    /** Human-readable statement (optional) */
140
    statement?: string;
141
    /** Request ID (optional) */
142
    requestId?: string;
143
    /** Additional resources (optional) */
144
    resources?: string[];
145
  }
146

147
  /**
148
   * Session authentication request structure
149
   */
150
  interface SessionAuthenticateRequest {
151
    /** Request parameters */
152
    params: SessionAuthenticateRequestParams;
153
    /** Verification context */
154
    verifyContext: Verify.Context;
155
  }
156

157
  /**
158
   * Session authentication request parameters
159
   */
160
  interface SessionAuthenticateRequestParams {
161
    /** Authentication requester */
162
    requester: Participant;
163
    /** Authentication parameters */
164
    authPayload: PayloadParams;
165
    /** Expiration timestamp */
166
    expiryTimestamp: number;
167
  }
168

169
  /**
170
   * Authentication participant with metadata
171
   */
172
  interface Participant {
173
    /** Participant's public key */
174
    publicKey: string;
175
    /** Participant metadata */
176
    metadata: CoreTypes.Metadata;
177
  }
178
}
179
```
180

181
### Authentication Parameters and Responses
182

183
Request parameters, approval structures, and response types for authentication flows.
184

185
```typescript { .api }
186
namespace AuthTypes {
187
  /**
188
   * Parameters for formatting auth messages
189
   */
190
  type FormatMessageParams = PayloadParams;
191

192
  /**
193
   * Base parameters for auth requests
194
   */
195
  interface BaseAuthRequestParams {
196
    /** Chain identifier */
197
    chainId: string;
198
    /** Domain requesting authentication */
199
    domain: string;
200
    /** Random nonce */
201
    nonce: string;
202
    /** Authentication URI */
203
    uri: string;
204
  }
205

206
  /**
207
   * Full authentication request parameters
208
   */
209
  interface RequestParams extends BaseAuthRequestParams {
210
    /** Expiration timestamp (optional) */
211
    expiry?: number;
212
    /** Not before timestamp (optional) */
213
    nbf?: string;
214
    /** Human-readable statement (optional) */
215
    statement?: string;
216
    /** Request ID (optional) */
217
    requestId?: string;
218
    /** Additional resources (optional) */
219
    resources?: string[];
220
  }
221

222
  /**
223
   * Pending authentication request
224
   */
225
  interface PendingRequest {
226
    /** Request ID */
227
    id: number;
228
    /** Request parameters */
229
    params: SessionAuthenticateParams;
230
    /** Verification context */
231
    verifyContext: Verify.Context;
232
  }
233

234
  /**
235
   * Parameters for approving session authentication
236
   */
237
  interface ApproveSessionAuthenticateParams {
238
    /** Request ID */
239
    id: number;
240
    /** Authentication objects */
241
    auths: Cacao[];
242
  }
243

244
  /**
245
   * Response parameters for session authentication
246
   */
247
  interface SessionAuthenticateResponseParams {
248
    /** Cached CACAOs */
249
    cacaos: Cacao[];
250
    /** Responder information */
251
    responder: Participant;
252
  }
253

254
  /**
255
   * Authentication error response
256
   */
257
  interface AuthErrorResponse {
258
    /** Error code */
259
    code: number;
260
    /** Error message */
261
    message: string;
262
  }
263

264
  /**
265
   * Authentication response type (success or error)
266
   */
267
  type AuthResponse = SessionAuthenticateResponseParams | AuthErrorResponse;
268

269
  /**
270
   * Authentication response result
271
   */
272
  interface AuthenticateResponseResult {
273
    /** Session topic */
274
    topic: string;
275
    /** Session structure */
276
    session?: SessionTypes.Struct;
277
  }
278
}
279
```
280

281
### Authentication Events and Configuration
282

283
Event types, arguments, and configuration options for authentication flows.
284

285
```typescript { .api }
286
namespace AuthTypes {
287
  /**
288
   * Authentication event type
289
   */
290
  type Event = "session_authenticate";
291

292
  /**
293
   * Base event arguments structure
294
   */
295
  interface BaseEventArgs<T = {}> {
296
    /** Event ID */
297
    id: number;
298
    /** Event topic */
299
    topic: string;
300
    /** Event parameters */
301
    params: T;
302
  }
303

304
  /**
305
   * All authentication event argument types
306
   */
307
  interface EventArguments {
308
    session_authenticate: SessionAuthenticateRequest;
309
  }
310

311
  /**
312
   * Authentication request event arguments
313
   */
314
  interface AuthRequestEventArgs extends BaseEventArgs<SessionAuthenticateParams> {
315
    /** Verification context */
316
    verifyContext: Verify.Context;
317
  }
318

319
  /**
320
   * Authentication response event arguments
321
   */
322
  type AuthResponseEventArgs = BaseEventArgs<AuthResponse>;
323

324
  /**
325
   * Authentication client options
326
   */
327
  interface Options {
328
    /** WalletConnect Cloud project ID */
329
    projectId: string;
330
    /** Client metadata */
331
    metadata: CoreTypes.Metadata;
332
    /** Include optional namespaces (default: false) */
333
    includeOptionalNamespaces?: boolean;
334
  }
335

336
  /**
337
   * Authentication metadata structure
338
   */
339
  interface Metadata extends CoreTypes.Metadata {
340
    /** Additional authentication-specific metadata */
341
    [key: string]: any;
342
  }
343

344
  /**
345
   * Authentication event callback
346
   */
347
  interface EventCallback<T = any> {
348
    resolve: (value: T) => void;
349
    reject: (reason: any) => void;
350
  }
351
}
352
```
353

354
### JSON-RPC Method Definitions
355

356
JSON-RPC method definitions and parameter types for WalletConnect protocol communication.
357

358
```typescript { .api }
359
namespace JsonRpcTypes {
360
  /**
361
   * Default JSON-RPC response type
362
   */
363
  type DefaultResponse = true | ErrorResponse;
364

365
  /**
366
   * WalletConnect method names for JSON-RPC communication
367
   */
368
  type WcMethod = 
369
    | "wc_sessionPropose"
370
    | "wc_sessionSettle" 
371
    | "wc_sessionUpdate"
372
    | "wc_sessionExtend"
373
    | "wc_sessionRequest"
374
    | "wc_sessionEvent"
375
    | "wc_sessionDelete"
376
    | "wc_sessionPing"
377
    | "wc_sessionAuthenticate";
378

379
  /**
380
   * Request parameters for all WC methods
381
   */
382
  interface RequestParams {
383
    wc_sessionPropose: {
384
      relays: RelayerTypes.ProtocolOptions[];
385
      requiredNamespaces: ProposalTypes.RequiredNamespaces;
386
      optionalNamespaces?: ProposalTypes.OptionalNamespaces;
387
      sessionProperties?: ProposalTypes.SessionProperties;
388
      proposer: SessionTypes.Participant;
389
    };
390
    wc_sessionSettle: {
391
      relay: RelayerTypes.ProtocolOptions;
392
      namespaces: SessionTypes.Namespaces;
393
      controller: SessionTypes.Participant;
394
      expiry: number;
395
    };
396
    wc_sessionUpdate: {
397
      namespaces: SessionTypes.Namespaces;
398
    };
399
    wc_sessionExtend: {};
400
    wc_sessionRequest: {
401
      request: {
402
        method: string;
403
        params: any;
404
      };
405
      chainId: string;
406
    };
407
    wc_sessionEvent: {
408
      event: {
409
        name: string;
410
        data: any;
411
      };
412
      chainId: string;
413
    };
414
    wc_sessionDelete: {
415
      code: number;
416
      message: string;
417
    };
418
    wc_sessionPing: {};
419
    wc_sessionAuthenticate: {
420
      authPayload: AuthTypes.PayloadParams;
421
      requester: AuthTypes.Participant;
422
      expiryTimestamp: number;
423
    };
424
  }
425

426
  /**
427
   * Response results for all WC methods
428
   */
429
  interface Results {
430
    wc_sessionPropose: DefaultResponse;
431
    wc_sessionSettle: DefaultResponse;
432
    wc_sessionUpdate: DefaultResponse;
433
    wc_sessionExtend: DefaultResponse;
434
    wc_sessionRequest: any;
435
    wc_sessionEvent: DefaultResponse;
436
    wc_sessionDelete: DefaultResponse;
437
    wc_sessionPing: DefaultResponse;
438
    wc_sessionAuthenticate: {
439
      cacaos: AuthTypes.Cacao[];
440
      responder: AuthTypes.Participant;
441
    };
442
  }
443

444
  /**
445
   * JSON-RPC error type
446
   */
447
  type Error = ErrorResponse;
448
}
449
```
450

451
### Pending Request Management
452

453
Pending request types and store interface for managing authentication requests.
454

455
```typescript { .api }
456
namespace PendingRequestTypes {
457
  /**
458
   * Pending request structure
459
   */
460
  interface Struct {
461
    /** Request ID */
462
    id: number;
463
    /** Request topic */
464
    topic: string;
465
    /** Request parameters */
466
    params: any;
467
    /** Verification context */
468
    verifyContext: Verify.Context;
469
  }
470
}
471

472
/**
473
 * Store interface for pending requests
474
 */
475
type IPendingRequest = IStore<PendingRequestTypes.Struct>;
476
```
477

478
**Usage Examples:**
479

480
```typescript
481
import { AuthTypes, JsonRpcTypes } from "@walletconnect/types";
482

483
// Create CACAO for authentication
484
const cacao: AuthTypes.Cacao = {
485
  h: { t: "CAIP-122" },
486
  p: {
487
    domain: "example.com",
488
    aud: "https://example.com/app",
489
    version: "1",
490
    nonce: "random-nonce-123",
491
    iat: new Date().toISOString(),
492
    statement: "Sign in to Example App"
493
  },
494
  s: {
495
    t: "eip191",
496
    s: "0x..."
497
  }
498
};
499

500
// Session authentication parameters
501
const authParams: AuthTypes.SessionAuthenticateParams = {
502
  chains: ["eip155:1", "eip155:137"],
503
  domain: "example.com",
504
  nonce: "random-nonce-456", 
505
  uri: "https://example.com/app",
506
  statement: "Sign in to access your wallet",
507
  resources: ["https://example.com/terms"]
508
};
509

510
// Authentication request
511
const authRequest: JsonRpcTypes.RequestParams["wc_sessionAuthenticate"] = {
512
  authPayload: {
513
    chainId: "eip155:1",
514
    domain: "example.com",
515
    nonce: "random-nonce-789",
516
    uri: "https://example.com/app",
517
    version: "1"
518
  },
519
  requester: {
520
    publicKey: "0x04...",
521
    metadata: {
522
      name: "Example dApp",
523
      description: "A sample decentralized application",
524
      url: "https://example.com",
525
      icons: ["https://example.com/icon.png"]
526
    }
527
  },
528
  expiryTimestamp: Date.now() + 300000 // 5 minutes
529
};
530

531
// Approve authentication
532
const approveParams: AuthTypes.ApproveSessionAuthenticateParams = {
533
  id: 1,
534
  auths: [cacao]
535
};
536
```