Skip to content

Commit c2c9190

Browse files
marcoscaceresTallTedtimcappalli
authored
Editorial: add API section (#304)
* Editoral: add API section * Explain flow form DC to CM and back * Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com> * small tweak --------- Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com> Co-authored-by: Tim Cappalli <tim@cloudauth.dev>
1 parent f0e3b5a commit c2c9190

File tree

1 file changed

+160
-39
lines changed

1 file changed

+160
-39
lines changed

‎index.html

Lines changed: 160 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -316,40 +316,161 @@ <h2>
316316
</li>
317317
</ul>
318318
<h2>
319-
Extensions to `CredentialRequestOptions` dictionary
319+
The Digital Credentials API
320320
</h2>
321+
<p>
322+
The Digital Credentials API leverages the [[[credential-management]]]
323+
specificaion, allowing [=user agents=] to mediate the [=digital
324+
credential/issuance=] and [=digital credential/presentation=] of
325+
[=digital credentials=].
326+
</p>
327+
<p>
328+
The API allows [=digital credential/presentation request|requesting=] a
329+
[=digital credential=] from the user agent, which in turn presents a
330+
[=credential chooser=] to the user, allowing them to select a [=digital
331+
credential=] that can fulfill the request. This is done by the website
332+
calling the `navigator.credentials.`{{CredentialsContainer/get()}}
333+
method, which runs the [=request a credential=] algorithm of
334+
[[[credential-management]]]. That algorithm then calls back into this
335+
specification's {{DigitalCredential}} interface's
336+
{{DigitalCredential/[[DiscoverFromExternalSource]](origin, options,
337+
sameOriginWithAncestors)}} internal method.
338+
</p>
339+
<p>
340+
Additionally, the API also allows [=digital credential/Issuance
341+
request|requesting issuance=] of a [=digital credential=], which
342+
initiates an mediated issuance flow between the user agent and/or a
343+
[=holder=]. This is done by calling the
344+
`navigator.credentials.`{{CredentialsContainer/create()}} method, which
345+
runs the [=create a credential=] algorithm of
346+
[[[credential-management]]]. That algorithm then calls back into this
347+
specification's {{DigitalCredential}} interface's
348+
{{Credential/[[Create]](origin,options, sameOriginWithAncestors)}}
349+
internal method.
350+
</p>
351+
<p>
352+
Please see [[[#credential-management-integration]]] for complete details
353+
of how to integrate with the [[[credential-management]]] specification.
354+
</p>
355+
<aside class="example" title="Requesting a digital credential">
356+
<p>
357+
The following example shows how to request a digital credential using
358+
the Digital Credentials API. The entry point for the API is the
359+
`navigator.credentials.`{{CredentialsContainer/get()}} method, which is
360+
used to request a [=digital credential=] from the user agent. If the
361+
user agent supports [=digital credential/presentation
362+
requests|presentation=], it allows the user to select a digital
363+
credential through a [=credential chooser=]:
364+
</p>
365+
<pre class="html">
366+
&lt;button&gt;Verify Identity&lt;/button&gt;
367+
&lt;script&gt;
368+
const button = document.querySelector("button");
369+
button.addEventListener("click", async () =&gt; {
370+
try {
371+
const credential = await navigator.credentials.get({
372+
digital: {
373+
requests: [{
374+
protocol: "example-protocol",
375+
data: { /* request data */ }
376+
}]
377+
}
378+
});
379+
380+
// Post it back to the server for decryption and verification
381+
const response = await fetch("/verify-credential", {
382+
method: "POST",
383+
headers: {
384+
"Content-Type": "application/json"
385+
},
386+
body: JSON.stringify(credential, null, 2)
387+
});
388+
389+
// Check response
390+
if (!response.ok) {
391+
throw new Error("Failed to verify credential");
392+
}
393+
394+
// Render the verification result
395+
displayVerificationResult(await response.json());
396+
397+
} catch (error) {
398+
console.error("Error requesting digital credential:", error);
399+
}
400+
});
401+
&lt;/script&gt;
402+
</pre>
403+
</aside>
404+
<p>
405+
Simliarly, when a site needs to [=digital credential/issuance|issue=] a
406+
digital credential, the Digital Credentials API mediates the issuance of a
407+
digital credential between the site, the user agent, and the [=holder=].
408+
</p>
409+
<aside class="example" title="Issuing a digital credential">
410+
<p>
411+
The following example shows how to request the issuance of a digital
412+
credential using the Digital Credentials API. To issue a digital
413+
credential, a site calls the
414+
`navigator.credentials.`{{CredentialsContainer/create()}} method,
415+
which, if the user agent supports issuance, would initiate the issuance
416+
flow:
417+
</p>
418+
<pre class="html">
419+
&lt;button&gt;Request Digital Credential Issuance&lt;/button&gt;
420+
&lt;script&gt;
421+
const button = document.querySelector("button");
422+
button.addEventListener("click", async () =&gt; {
423+
try {
424+
const credential = await navigator.credentials.create({
425+
digital: {
426+
requests: [{
427+
protocol: "example-issuance-protocol",
428+
data: { /* issuance request data */ }
429+
}]
430+
}
431+
});
432+
} catch (error) {
433+
console.error("Error issuing digital credential:", error);
434+
}
435+
});
436+
&lt;/script&gt;
437+
</pre>
438+
</aside>
439+
<h3>
440+
Extensions to `CredentialRequestOptions` dictionary
441+
</h3>
321442
<pre class="idl">
322443
partial dictionary CredentialRequestOptions {
323444
DigitalCredentialRequestOptions digital;
324445
};
325446
</pre>
326-
<h3>
447+
<h4>
327448
The `digital` member
328-
</h3>
449+
</h4>
329450
<p>
330451
The <dfn data-dfn-for="CredentialRequestOptions">digital</dfn> member
331452
allows for options to configure the request for a [=digital credential=].
332453
</p>
333-
<h2>
454+
<h3>
334455
The `DigitalCredentialRequestOptions` dictionary
335-
</h2>
456+
</h3>
336457
<pre class="idl">
337458
dictionary DigitalCredentialRequestOptions {
338459
sequence&lt;DigitalCredentialGetRequest&gt; requests;
339460
};
340461
</pre>
341-
<h3>
462+
<h4>
342463
The `requests` member
343-
</h3>
464+
</h4>
344465
<p>
345466
The <dfn data-dfn-for="DigitalCredentialRequestOptions">requests</dfn>
346467
specify an [=digital credential/exchange protocol=] and [=digital
347468
credential/request data=], which the user agent MAY match against a
348469
holder's software, such as a digital wallet.
349470
</p>
350-
<h2>
471+
<h3>
351472
The `DigitalCredentialGetRequest` dictionary
352-
</h2>
473+
</h3>
353474
<p>
354475
The {{DigitalCredentialGetRequest}} dictionary represents a [=digital
355476
credential/presentation request=]. It is used to specify an [=digital
@@ -363,9 +484,9 @@ <h2>
363484
required object data;
364485
};
365486
</pre>
366-
<h3>
487+
<h4>
367488
The `protocol` member
368-
</h3>
489+
</h4>
369490
<p>
370491
The <dfn data-dfn-for="DigitalCredentialGetRequest">protocol</dfn> member
371492
denotes the [=digital credential/exchange protocol=].
@@ -375,49 +496,49 @@ <h3>
375496
of the well-defined protocol identifiers defined in
376497
[[[#protocol-registry]]] or a custom protocol identifier.
377498
</p>
378-
<h3>
499+
<h4>
379500
The `data` member
380-
</h3>
501+
</h4>
381502
<p>
382503
The <dfn data-dfn-for="DigitalCredentialGetRequest">data</dfn> member is
383504
the [=digital credential/request data=] to be handled by the holder's
384505
credential provider, such as a digital identity wallet.
385506
</p>
386-
<h2>
507+
<h3>
387508
Extensions to `CredentialCreationOptions` dictionary
388-
</h2>
509+
</h3>
389510
<pre class="idl">
390511
partial dictionary CredentialCreationOptions {
391512
DigitalCredentialCreationOptions digital;
392513
};
393514
</pre>
394-
<h3>
515+
<h4>
395516
The `digital` member
396-
</h3>
517+
</h4>
397518
<p>
398519
The <dfn data-dfn-for="CredentialCreationOptions">digital</dfn> member
399520
allows for options to configure the issuance of a [=digital credential=].
400521
</p>
401-
<h2>
522+
<h3>
402523
The `DigitalCredentialCreationOptions` dictionary
403-
</h2>
524+
</h3>
404525
<pre class="idl">
405526
dictionary DigitalCredentialCreationOptions {
406527
sequence&lt;DigitalCredentialCreateRequest&gt; requests;
407528
};
408529
</pre>
409-
<h3>
530+
<h4>
410531
The `requests` member
411-
</h3>
532+
</h4>
412533
<p>
413534
The <dfn data-dfn-for="DigitalCredentialCreationOptions">requests</dfn>
414535
specify an [=digital credential/issuance protocol=] and [=digital
415536
credential/request data=], which the user agent MAY forward to a
416537
[=holder=].
417538
</p>
418-
<h2>
539+
<h3>
419540
The `DigitalCredentialCreateRequest` dictionary
420-
</h2>
541+
</h3>
421542
<p>
422543
The {{DigitalCredentialCreateRequest}} dictionary represents an [=digital
423544
credential/issuance request=]. It is used to specify an [=digital
@@ -431,9 +552,9 @@ <h2>
431552
required object data;
432553
};
433554
</pre>
434-
<h3>
555+
<h4>
435556
The `protocol` member
436-
</h3>
557+
</h4>
437558
<p>
438559
The <dfn data-dfn-for="DigitalCredentialCreateRequest">protocol</dfn>
439560
member denotes the [=digital credential/issuance protocol=].
@@ -443,17 +564,17 @@ <h3>
443564
of the well-defined keys defined in [[[#protocol-registry]]] or any other
444565
custom one.
445566
</p>
446-
<h3>
567+
<h4>
447568
The `data` member
448-
</h3>
569+
</h4>
449570
<p>
450571
The <dfn data-dfn-for="DigitalCredentialCreateRequest">data</dfn> member
451572
is the [=digital credential/request data=] to be handled by the holder's
452573
credential provider, such as a digital identity wallet.
453574
</p>
454-
<h2>
575+
<h3>
455576
The `DigitalCredential` interface
456-
</h2>
577+
</h3>
457578
<p>
458579
The <dfn>DigitalCredential</dfn> interface represents a conceptual
459580
[=digital credential=].
@@ -480,31 +601,27 @@ <h2>
480601
<p>
481602
{{DigitalCredential}} instances are [=Credential/origin bound=].
482603
</p>
483-
<h3>
604+
<h4>
484605
The `protocol` member
485-
</h3>
606+
</h4>
486607
<p>
487608
The <dfn data-dfn-for="DigitalCredential">protocol</dfn> member is the
488609
[=digital credential/exchange protocol=] that was used to request the
489610
[=digital credential=], or the [=digital credential/issuance protocol=]
490611
that was used to issue the [=digital credential=].
491612
</p>
492-
<h3>
613+
<h4>
493614
The `data` member
494-
</h3>
615+
</h4>
495616
<p>
496617
The <dfn data-dfn-for="DigitalCredential">data</dfn> member is the
497618
credential's response data. It contains the subset of JSON-parseable
498619
object types.
499620
</p>
500-
<h2>
501-
Integration with Credential Management API
502-
</h2>
503-
<aside class="issue" data-number="65"></aside>
504-
<h3>
621+
<h4>
505622
The <dfn data-dfn-for="DigitalCredential">userAgentAllowsProtocol()</dfn>
506623
method
507-
</h3>
624+
</h4>
508625
<p>
509626
The {{DigitalCredential/userAgentAllowsProtocol()}} method allows digital
510627
credential [=verifiers=] to determine which [=digital credential/exchange
@@ -539,6 +656,10 @@ <h3>
539656
`false`.
540657
</li>
541658
</ol>
659+
<h2 id="credential-management-integration">
660+
Integration with Credential Management API
661+
</h2>
662+
<aside class="issue" data-number="65"></aside>
542663
<h3>
543664
[[\DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)
544665
internal method

0 commit comments

Comments
 (0)