-
Notifications
You must be signed in to change notification settings - Fork 53
Expand file tree
/
Copy pathindex.html
More file actions
4581 lines (4259 loc) · 181 KB
/
Copy pathindex.html
File metadata and controls
4581 lines (4259 loc) · 181 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title style="font-size: 10px;">VCALM v1.0</title>
<meta content='text/html; charset=utf-8' http-equiv='Content-Type'>
<script class="remove"
src="https://www.w3.org/Tools/respec/respec-w3c"></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/digitalbazaar/respec-oas@1.0.1/dist/main.js"></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/digitalbazaar/respec-mermaid@1.3.0/dist/main.js"></script>
<script class="remove" type="text/javascript">
var respecConfig = {
// the W3C WG and public mailing list
group: "vc",
wgPublicList: "public-vc-wg",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vcalm-1.0",
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
// W3C Candidate Recommendation information
//crEnd: "2021-05-04",
//implementationReportURI: "https://w3c.github.io/vcalm-test-suite/",
// Editor's Draft URL
//latestVersion: "https://www.w3.org/community/reports/credentials/CG-FINAL-vcalm-20260320/",
//edDraftURI: "https://w3c.github.io/vcalm/",
// subtitle for the spec
subtitle: "A Verifiable Credential API for Lifecycle Management",
// if you wish the publication date to be other than today, set this
//publishDate: "2026-03-20",
// previously published draft, uncomment this and set its
// YYYY-MM-DD date and its maturity status
//previousPublishDate: "2021-03-01",
//previousMaturity: "WD",
// automatically allow term pluralization
pluralize: true,
// extend the bibliography entries
localBiblio: {
"ISO18004": {
title: "ISO18004:2024: QR Code Bar Code Symbology Specification",
href: "https://www.iso.org/standard/83389.html",
status: "Published",
publisher: "ISO"
},
"DCAPI": {
title: "Digital Credential API",
href: "https://www.w3.org/TR/digital-credentials/",
status: "WD",
publisher: "W3C"
},
"OID4VCI": {
title: "OpenID for Verifiable Credential Issuance v1.0",
href: "https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html",
status: "WD",
publisher: "OpenID Foundation"
},
"OID4VP": {
title: "OpenID for Verifiable Presentations v1.0",
href: "https://openid.net/specs/openid-4-verifiable-presentations-1_0.html",
status: "WD",
publisher: "OpenID Foundation"
},
"VC-RECOG-ENT": {
title: "Recognized Entities v1.0",
href: "https://www.w3.org/TR/vc-recognized-entities/",
status: "WD",
publisher: "W3C"
},
"ZCAP": {
title: "Authorization Capabilities for Linked Data v0.3",
href: "https://w3c-ccg.github.io/zcap-spec/",
status: "WD",
publisher: "W3C Credentials Community Group"
}
},
xref: [
"web-platform", "infra", "url", "vc-data-model-2.0", "did", "vc-data-integrity", "vc-recognized-entities"
],
github: {
repoURL: "https://github.com/w3c/vcalm/",
branch: "main"
},
includePermalinks: false,
maxTocLevel: 3,
// Uncomment these to use the respec extension that generates a list of
// normative statements:
preProcess: [window.respecMermaid.createFigures, window.respecOasComponentTable.injectOasComponentTables] ,
postProcess: [window.respecOas.injectOas],
oas: ["oas.yaml"],
lint: {
"no-unused-dfns": false,
"informative-dfn": false
},
// list of specification editors
editors: [{
name: "Patrick St. Louis",
url: "https://www.linkedin.com/in/patrick-stlouis/",
company: "Open Security and Identity",
companyURL: "https://opsecid.ca/",
w3cid: 162334
}, {
name: "Kayode Ezike",
url: "https://www.linkedin.com/in/kayodeezike",
company: "Gobekli",
companyURL: "https://gobekli.io/",
w3cid: 106964
}, {
name: "Manu Sporny",
url: "https://www.linkedin.com/in/manusporny/",
company: "Digital Bazaar",
companyURL: "https://www.digitalbazaar.com/",
w3cid: 41758
}, {
name: "Ted Thibodeau Jr",
url: "https://github.com/TallTed",
company: "OpenLink Software",
companyURL: "https://www.openlinksw.com/",
w3cid: 42501
}],
// list of specification authors
authors: [{
name: "Dave Longley",
url: "https://github.com/dlongley",
company: "Digital Bazaar",
companyURL: "https://www.digitalbazaar.com/",
w3cid: 48025
}, {
"name": "Joe Andrieu",
"url": "https://www.linkedin.com/in/joe-andrieu/",
"company": "Legendary Requirements",
"companyURL": "https://legreq.com/",
"w3cid": 97261
}, {
name: "Markus Sabadello",
url: "https://www.linkedin.com/in/markus-sabadello-353a0821",
company: "Danube Tech",
companyURL: "https://danubetech.com/",
w3cid: 46729
}, {
name: "Kayode Ezike",
url: "https://www.linkedin.com/in/kayodeezike",
company: "Gobekli",
companyURL: "https://gobekli.io/",
w3cid: 106964
}, {
name: "Nate Otto",
company: "Skybridge Skills",
companyURL: "https://skybridgeskills.com/",
w3cid: 72953
}, {
name: "Eric Schuh",
company: "Legendary Requirements",
companyURL: "https://legreq.com/",
w3cid: 152695
}, {
name: "Patrick St. Louis",
url: "https://www.linkedin.com/in/patrick-stlouis/",
company: "Open Security and Identity",
companyURL: "https://opsecid.ca/",
w3cid: 162334
}],
otherLinks: [{
key: "Meetings:",
data: [{
value: "View next scheduled meeting",
href: "https://www.w3.org/events/meetings/8a197c4d-46a1-4377-b02c-0e05dbf1da7a/#next"
}]
}]
};
</script>
<style>
code {
color: rgb(199, 73, 0);
font-weight: bold;
}
pre {
overflow-x: auto;
white-space: pre-wrap;
}
pre .highlight {
font-weight: bold;
color: Green;
}
pre .subject {
font-weight: bold;
color: RoyalBlue;
}
pre .property {
font-weight: bold;
color: DarkGoldenrod;
}
pre .comment {
font-weight: bold;
color: SteelBlue;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
code a[href] {
color: inherit;
border-bottom: none;
}
code a[href]:hover {
border-bottom: 1px solid #c63501;
}
ol.algorithm {
counter-reset: numsection;
list-style-type: none;
}
ol.algorithm li {
margin: 0.5em 0;
}
ol.algorithm li:before {
font-weight: bold;
counter-increment: numsection;
content: counters(numsection, ".") ") ";
}
table.simple {
border-collapse: collapse;
margin: 25px 0;
min-width: 75%;
border: 1px solid #dddddd;
}
table.simple thead tr {
background-color: #005a9c;
color: #ffffff;
text-align: left;
}
table.simple th,
table.simple td {
padding: 12px 15px;
vertical-align: top;
text-align: left;
}
table.simple tbody tr {
border-bottom: 1px solid #dddddd;
}
table.simple tbody tr:nth-of-type(even) {
background-color: #00000008;
}
table.simple tbody tr:last-of-type {
border-bottom: 2px solid #005a9c;
}
</style>
</head>
<body data-cite="vc-data-model">
<section id='abstract'>
<p>
Verifiable credentials provide a mechanism to express credentials on
the Web in a way that is cryptographically secure, privacy respecting,
and machine-verifiable. This specification provides data model and
HTTP protocols to issue, verify, present, and manage data used in such an
ecosystem.
</p>
</section>
<section id='sotd'>
<p>
This specification is in active development. Deployment in production systems is
discouraged unless you are participating in the weekly meetings that coordinate
activity around this specification.
</p>
</section>
<section class="informative">
<h1>Introduction</h1>
<p>
The Verifiable Credentials specification [[VC-DATA-MODEL-2.0]] provides a data
model and serialization to express digital credentials in a way that is
cryptographically secure, privacy respecting, and machine-verifiable. This
specification provides a set of HTTP Application Programming Interfaces (HTTP
APIs) and protocols for issuing, verifying, presenting, and managing Verifiable
Credentials.
</p>
<p>
When managing [=verifiable credentials=], there are two general types of APIs
that are contemplated. The first type of APIs are designed to be used within
a single security domain. The second type of APIs can be used to
communicate across different security domains. This specification defines
both types of APIs.
</p>
<p>
The APIs that are designed to be used within a single security domain are used by
systems that are operating on behalf of a single role such as an [=issuer=], [=verifier=],
or [=holder=]. One benefit of these APIs for the Verifiable Credentials ecosystem
is that they define a useful, common, and vetted modular architecture for
managing Verifiable Credentials. For example, this approach helps software
architects integrate with common components and speak a common language
when implementing systems that issue [=verifiable credentials=]. Knowing that
a particular architecture has been vetted is also beneficial for architects that
do not specialize in [=verifiable credentials=]. Documented architectures and
APIs increase market competition and reduce vendor lock-in and switching
costs.
</p>
<p>
The APIs that are designed to operate across multiple security domains are
used by systems that are communicating between two different roles in a
[=verifiable credential=] interaction, such as an API that is used to
communicate presentations between a [=holder=] and a [=verifier=]. In order to
achieve protocol interoperability in [=verifiable credentials=] interactions,
it is vital that these APIs be standardized. The additional benefits of
documenting these APIs are the same for documenting the
single-security-domain APIs: common, vetted architecture and APIs, increased
market competition, and reduced vendor lock-in and switching costs.
</p>
<p>
This specification contains the following sections that software architects
and implementers might find useful:
</p>
<ul class="bullet">
<li>
<a href="#design-goals-and-rationale"></a> specifies the high level design goals
that drove the formulation of this specification.
</li>
<li>
<a href="#architecture-overview"></a> highlights the different roles
and components that are contemplated by the architecture.
</li>
<li>
<a href="#terminology"></a> defines specific terms that are used throughout
the document.
</li>
<li>
<a href="#authorization"></a> elaborates upon the various forms of authorization
that can be used with the API.
</li>
<li>
<a href="#issuing"></a> describes the APIs for
issuing [=verifiable credentials=] as well as updating their status.
</li>
<li>
<a href="#verifying"></a> specifies the APIs for verifying both
[=verifiable credentials=] and verifiable presentations.
</li>
<li>
<a href="#presenting"></a> defines APIs for generating and deriving
[=verifiable presentations=] within a trust domain, as well as
exchanging [=verifiable presentations=] across trust domains.
</li>
<li>
Finally, Appendix <a href="#privacy-considerations"></a>, and
<a href="#security-considerations"></a> are provided to highlight factors
that implementers might consider when building systems that utilize the APIs
defined by this specification.
</li>
</ul>
<section class="informative">
<h2>Design Goals and Rationale</h2>
<p>
The Verifiable Credentials API is optimized towards the following design goals:
</p>
<table class="simple">
<thead>
<tr>
<th>
Goal
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Modularity
</td>
<td>
Implementers need only implement the APIs that are required for their use case
enabling modularity between Issuing, Verifying, and Presenting.
</td>
</tr>
<tr>
<td>
Simplicity
</td>
<td>
The number of APIs and optionality are kept to a minimum to ensure that they are
easy to implement and audit from a security standpoint.
</td>
</tr>
<tr>
<td>
Composability
</td>
<td>
The APIs are designed to be composable such that complex flows are possible
using a small number of simple API primitives.
</td>
</tr>
<tr>
<td>
Extensibility
</td>
<td>
Extensions to API endpoints are expected and catered to in the API design
enabling experimentation and the addition of value-added services on top of
the base API platform.
</td>
</tr>
</tbody>
</table>
<section class="notoc">
<h3>HTTP API Design Guidelines</h3>
<p>
A <a href="https://restfulapi.net/">RESTful API</a> approach was used as a basis
for the specification. Some endpoints use what is referred to as the
'controller' resource naming style. [[[?json-schema]]] is used to define the
acceptable inputs to the APIs.
</p>
</section>
</section>
<section class="informative">
<h2>
Architecture Overview
</h2>
<p>
The Verifiable Credentials Data Model defines three fundamental roles, the
[=issuer=], the [=verifier=], and the [=holder=].
</p>
<figure id="roles">
<img style="margin: auto; width: 33%; display: block;"
src="./diagrams/roles.svg"
alt="
Diagram showing the verifiable credential roles of Issuer, Holder, and Verifier">
<figcaption style="text-align: center;">
The roles defined by the Verifiable Credentials Data Model specification.
</figcaption>
</figure>
<p>
Actors fulfilling each of these roles may use a number of software or service
components to realize the API for exchanging Verifiable Credentials.
</p>
<p>
Each role associates with a role-specific Coordinator, Service, and Admin as
well as their own dedicated Storage Service. In addition, the [=issuer=] may also
manage a Status Service for revocable credentials issued by the [=issuer=].
</p>
<figure id="components">
<img style="margin: auto; width: 100%; display: block;"
src="diagrams/components.svg"
alt="API Components of Coordinators, Services, and Admin for Issuers, Verifiers, and Holders">
<figcaption style="text-align: center;">
API Components. Arrows indicate initiation of flows.
</figcaption>
</figure>
<p>
Any given implementation may choose to combine any or all of these
components into a single functional application. The boundaries and interfaces
between these components are defined in this specification to ensure
interoperability and substitutability across the Verifiable Credential
conformant ecosystem.
</p>
<p class="issue" title="Standardizing the architecture is of primary importance; component standards are secondary">
Based on this architectural thinking, we may want to frame this API as a
roadmap of related specifications, integrated in an extensible way for maximum
substitutability. Several technologies, such as EDVs and WebKMSs would likely
benefit from the crypto suite Approach taken for [=verifiable credential=] proofs. Defining a generic
mechanism that can be realized by any functionally conformant technology enables
flexibility while laying the groundwork with current existing functionality. In
this way, we may be able to acknowledge that elements like Key Services,
Storage, and Status are necessary parts of this API while deferring the
definition of how those elements work to specification already in development as
well as those yet to be written.
</p>
<p>
In addition to aggregating components into a single app, implementers may choose
to operationalize any given role over any number active instances of deployed
software. For example, a browser-based [=holder coordinator=] should be considered
as an amalgam of a web browser, various code running in that browser, one or
more web servers (in the case of cross-origin AJAX or remote embedded content),
and the code running on that server. Each of those elements runs as different
software packages in different configurations, each executing just part of the
overall functionality of the component. For the sake of this API, each
component satisfies all of its required functionality as a whole, regardless of
deployment architecture.
</p>
</section>
<section id="conformance">
<p>
A conforming <dfn>issuer service implementation</dfn> MUST provide the interface
described in Section [[[#issue-credential]]]. Other interfaces described in
Section [[[#issuing]]] MAY also be provided.
</p>
<p>
A conforming <dfn>verifier service implementation</dfn> MUST provide the
interface described in Section [[[#verify-credential]]] and Section
[[[#verify-presentation]]]. Other interfaces described in Section
[[[#verifying]]] MAY also be provided.
</p>
<p>
A conforming <dfn>holder service implementation</dfn> MUST provide the interface
described in Section [[[#get-exchange-protocols]]] and Section
[[[#participate-in-an-exchange]]]. Conformance to protocols, query languages,
and data formats described in Section [[[#initiating-interactions]]], Section
[[[#requesting-a-presentation]]], Section [[[#create-presentation]]], Section
[[[#presenting]]], and Section [[[#workflows-and-exchanges]]] MAY
also be provided.
</p>
<p>
A conforming <dfn>status service implementation</dfn> MUST provide the interface
described in Section [[[#update-status]]].
</p>
<p>
A conforming <dfn>workflow service implementation</dfn> MUST provide all
interfaces Section [[[#workflows-and-exchanges]]].
</p>
<p>
A conforming <dfn>service client implementation</dfn> MUST provide the
means to communicate with all REQUIRED interfaces provided by the
corresponding service implementation. That is, a
<em>status client implementation</em> provides means to communicate
with all mandatory interfaces exposed by a [=status service implementation=].
</p>
<p>
All implementations MAY provide functionality beyond this specification.
</p>
</section>
<section class="informative">
<h2>Terminology</h2>
<p>
Terminology used throughout this document is defined in the
<a data-cite="VC-DATA-MODEL-2.0#terminology">Terminology</a> section of the
[[[VC-DATA-MODEL-2.0]]] specification.
</p>
</section>
</section>
<section>
<h2>Architecture</h2>
One possible architecture for these software components is represented by the
architecture description below, as well as the diagram in the <a
href="#architecture-overview"></a> section. These representations were chosen
to make categorization of the different features in the specification clear,
enabling each component to be treated independently both for clarity of reading
and to highlight that each component can be implemented separately from any
other. However, this is not a prescriptive architecture; implementers can use as
many or as few software packages as desired to serve multiple roles; roles are
not required to be served by a single library or other software package nor are
software libraries or packages required to provide for particular roles in isolation
of others. It is also an expectation that single deployments of software or
system components can be for the purpose of multiple roles as needed for a
given use case.
<section>
<h3>Coordinators</h3>
<p>
A <dfn>coordinator</dfn> executes the business rules and policies set by the
associated role. Often this is a custom or proprietary [=coordinator=] developed
specifically for a single party acting in that role; it is the integration glue
that connects the controlling party to the [=verifiable credential=] ecosystem.
</p>
<p>
[=Coordinators=] might provide a visual user interface, depending on the
implementation. Pure command-line or continuously running services might also be
able to realize this component.
</p>
<p>
With the exception of the [=status service=], all role-to-role communication is
between [=coordinators=] acting on behalf of its particular actor to fulfill its
role.
</p>
<p>
An <dfn>issuer coordinator</dfn> executes the rules about who gets what
credentials, including how the parties creating or receiving those credentials
are authenticated and authorized. Typically the [=issuer coordinator=]
integrates the [=issuer=]'s back-end system with the [=issuer service=]. This
integration uses whatever technologies are appropriate; the interfaces between
the [=issuer coordinator=] and back-end services are out of scope for this
specification. The [=issuer coordinator=] drives the [=issuer service=].
</p>
<p>
A <dfn>verifier coordinator</dfn> communicates with a [=verifier service=] to
first check authenticity and timeliness of a given [=verifiable credential=] or
[=verifiable presentation=], then applies the [=verifier=]'s business rules
before ultimately accepting or rejecting that [=verifiable credential=] or
[=verifiable presentation=]. Such business rules might include evaluating the
[=issuer=] of a particular claim or simply checking a configured allow-list. The
[=verifier coordinator=] exposes an API for submitting [=verifiable
credentials=] to the [=verifier=] per the [=verifier=]'s policies. For example,
the [=verifier coordinator=] might only accept [=verifiable credentials=] from
current users of the [=verifier=]'s other services. These rules typically
require bespoke integration with the [=verifier=]'s existing back-end.
</p>
<p>
A <dfn>holder coordinator</dfn> executes the business rules for approving the
flow of credentials under the control of the [=holder=], from [=issuers=] to
[=verifiers=]. In some deployments this means exposing a user interface that
gives individual [=holders=] a visual way to authorize or approve [=verifiable
credential=] storage or transfer. Some functionality of the [=holder
coordinator=] is commonly referred to as a <dfn>digital wallet</dfn>. In this
API, the [=holder coordinator=] initiates all flows. They request [=verifiable
credentials=] from [=issuers=]. They decide if, and when, to share those
[=verifiable credentials=] with [=verifiers=]. Within this API, there is no way
for either the [=issuer=] or the [=verifier=] to initiate the transfer of a
[=verifiable credential=]. In many scenarios, the [=holder coordinator=] is
expected to be under the control of an individual human, ensuring a person is
directly involved in the communication of [=verifiable credentials=], even if
only at the step of authorizing the transfer. However, some [=verifiable
credentials=] are about organizations, not individuals. How individuals using
[=holder coordinator=]s related to organizations, and in particular, how
organizational credentials are securely shared with, and presented by, (legal)
agents of those organizations is not in scope for this specification.
</p>
</section>
<section>
<h3>Services</h3>
<p>
A <dfn>service</dfn> provides lower-level API functionality, driven by its
associated [=coordinator=], and is designed to enable infrastructure providers
to offer [=verifiable credential=] capability through service delivery
architectures such as Software-as-a-Service. All services expose HTTP endpoints
to their authorized [=coordinators=], which are themselves operating on behalf
of an associated role. Although deployed services might provide their own HTML
interfaces, such interfaces are out of scope for this specification. Only the
HTTP endpoints of services are defined herein.
</p>
<p>
An <dfn>issuer service</dfn> takes requests to issue [=verifiable credentials=]
from authorized [=issuer coordinators=] and return conforming [=verifiable
credentials=]. This service has access to cryptographic material, such as
private keys or key services which utilize private keys, in order to create the
proofs for [=verifiable credentials=]. The API between the [=issuer service=]
and its associated cryptographic key management service is out of scope for this
specification.
</p>
<p>
A <dfn>verifier service</dfn> takes requests to verify [=verifiable
credentials=] and [=verifiable presentations=] and returns the result of
checking their proofs and status (if present). The service only checks the
authenticity and timeliness of the [=verifiable credential=], leaving the
[=verifier coordinator=] to finish applying any necessary business rules.
</p>
<p>
A <dfn>holder service</dfn> takes requests to create Verifiable Presentations
from an optional set of [=verifiable credentials=] and returns well-formed, signed Verifiable
Presentations containing those VCs. These [=verifiable presentation=]s are used with [=issuers=] to
demonstrate control over DIDs prior to [=verifiable credential=] issuance and with [=verifiers=] to present
specific VCs.
</p>
<p>
A <dfn>status service</dfn> provides a privacy-preserving means of publishing
and checking the status of any Verifiable Credentials issued by the [=issuer=].
Implementers of verifier services are encouraged to understand the privacy
implications of checking status by referring to the respective status
specification used by the verifiable credential. For specific mechanisms by
which to manage [=verifiable credential=] statuses, it's recommended to refer to
well-known external specifications, such as the [[VC-BITSTRING-STATUS-LIST]].
</p>
<p>
A <dfn>storage service</dfn> is used by each actor in the system to store their own verifiable credentials
and corresponding data, as needed. Several known
implementations use secure data storage such as encrypted data vaults for
storing the [=holder=]'s [=verifiable credentials=] and use cryptographic authorizations to grant access to
those [=verifiable credentials=] to [=verifier coordinator=]s, as directed by the [=holder=]. In-browser
retrieval of such stored credentials can enable web-based [=verifier
coordinator=]s to integrate data from the [=holder=] without sharing that data with
the [=verifier=]—the data is only ever present in the browser. Authorizing
third-party remote access to [=holder=] storage is likely in-scope for this API,
although we expect this to be defined using extensible mechanisms to support a
variety of storage and authorization approaches.
</p>
<p>
The [=issuer=] and [=verifier=] storage solutions may or may not use secure data
storage. Since all such storage interaction is moderated by the bespoke [=issuer=]
and Storage Coordinators, any necessary integrations can simply be part of that
bespoke customization. We expect different implementations to compete on the
ease of integration into various back-end storage platforms.
</p>
<p>
A <dfn>workflow service</dfn> provides a way for coordinators to automate
specific interactions for specific users. Each role ([=holder=], [=issuer=], and
[=verifier=]) can run their own workflow service to create and manage exchanges that
realize particular workflows. Administrators configure the workflow system to
support particular flows. Then, when the business rules justify it, coordinators
create exchanges at their workflow service and give access to those exchanges to
any authorized party.
</p>
<p>
An <dfn>administration service</dfn> is an acknowledgement that each of the other
components need a way to be configured and managed, without prescribing the
interfaces or means of that configuration. Some components might use JSON files
to drive a command line interface. Others might expose HTML pages. It is
expected that different implementations will compete on the power, ease, and
flexibility of their administration and therefore, configuration is largely out
of scope for this specification. There are some places where some configuration
mechanisms are provided, such as in Section [[[#create-workflow]]], where there
was broad agreement to standardize some configuration parameters. As the market
matures, other areas of configuration standardization might occur in future
versions of this specification.
</p>
</section>
<section>
<h3>Instances</h3>
<p>
The APIs defined in this specification presume that they are attached to a
specific <dfn>instance</dfn> with an associated configuration that has been put
in place by a system administrator. When a client calls an endpoint on a
particular [=instance=], the [=instance=] uses the configuration and options
provided by the client to execute the action.
</p>
<p>
For example, the `/credentials/issue` endpoint can be provided at the end of a
longer URL such as `/instances/12345/credentials/issue`. In this case, it is the
[=instance=] that is configured to know which cryptographic key to use for
issuance, whether or not a status list is involved, the type of credential to
issue, the credential format, and what additional options are possible on the
endpoint.
</p>
<p>
Software clients that call a particular [=instance=] might not have the
capability to configure an [=instance=], or be aware of the setup that the
administrator did on the instance other than the requisite details to make
appropriate use of it. Administration endpoints for configuring [=instances=]
could be provided by implementations but are not necessarily exposed as HTTP
APIs; configuration can also be done through configuration files or graphical
interfaces.
</p>
<p class="note"
title="A coordinator can use multiple service instances">
A coordinator instance can have access to multiple service instances in order to
support different use cases or a use case with complex flows. Runtime discovery
of service instance configuration is not defined by this specification as
services are expected to be known by the [=coordinator=] at the time of
deployment.
</p>
</section>
<section>
<h3>Configurations</h3>
<p>
Each [=coordinator=] or [=service=] [=instance=] is associated with a
specific configuration that drives its behavior. This section contains
how some of those configurations might be performed.
</p>
<section class="notoc">
<h4>Base URL</h4>
<p>
There are no restrictions put on the base URL for any particular [=instance=].
The URL paths used throughout this specification are shown as absolute paths and
their base URL MAY be the host name of the server (e.g.,
`website.example`), a subdomain (e.g., `api.website.example`, or
a path within that domain (e.g., <code>website.example/api</code>).
</p>
</section>
<section class="notoc">
<h3>Authorization</h3>
<p>
This API can be deployed in a variety of networking environments which might
contain hostile actors. As a result, conforming service implementations require
conforming [=service client implementations=] to utilize secure authorization
technologies when performing certain types of requests. Each HTTP endpoint
defined in this document specifies whether or not authorization is required when
performing a request. With the exception of the class of forbidden authorization
protocols discussed later in this section, this API is agnostic regarding
authorization mechanism.
</p>
<p>
This API is meant to be generic and useful in many scenarios that require the
issuance, possession, presentation, and/or verification of Verifiable
Credentials. To this end, implementers are advised to consider the following
classifications of use cases:
</p>
<ul>
<li>
<i>Public</i>. A Public API is one that can be called with no authorization.
Examples include an open witness or timestamp service (a trusted service that
can digitally sign a message with a timestamp for an audit trail purpose), or an
open retail coupon endpoint ("buy one, get one free"). Public verifiers might
also exist as well, to act as an agnostic third party in a trust scenario.
</li>
<li>
<i>Permissioned</i>. Permissioned authorization requires the entity making the
API call to, for example, have an access control token or a capability URL, or
to invoke a capability from a mutually trusted source. These permissions grant
access to the API, but make no assumptions about credential subjects, previous
interactions, or the like. Permissioned access is particularly useful in
service-to-service based workflows, where credential subjects are not directly
involved.
</li>
<li>
<i>Bound</i>. Bound authorization involves scenarios where the API calls are
tightly coupled, linked, or bound to another process, often out-of-band, that
has authenticated the holder/subject of the API interaction. These use cases
include, but are not limited to, issuance of subject-specific identity claims
directly to the subject in question, or verification of credentials to qualify
the holder for service at the verifier, for example. Examples of methods to bind
activity on one channel to an API call include <a
href="https://vcplayground.org/docs/#credential-handler-api-chapi">CHAPI</a> (the
<a href="https://vcplayground.org/docs/#credential-handler-api-chapi">Credential Handler API</a>), OIDC (OpenID Connect),
and GNAP (the Grant Negotiation and Authorization Protocol). Developers
implementing bound authorization will need to take steps to ensure the
appropriate level of assurance is achieved in the flow to properly protect the
binding.
</li>
</ul>
<p>
The rest of this section gives examples of the authorization technologies that
have been contemplated for use by conforming implementations. Other equivalent
authorization technologies can be used. Implementers are cautioned against using
non-standard or legacy authorization technologies.
</p>
<section class="notoc">
<h4>Forbidden Authorization</h4>
<p>
Requests to this API MUST NOT utilize any authorization protocol that includes
long-lived static credentials such as usernames and passwords or similar values
in those requests. An example of such a forbidden protocol is HTTP Basic
Authentication [[RFC7617]].
</p>
</section>
<section class="notoc">
<h4>Authorization Capabilities</h4>
<p>
If Authorization Capabilities (ZCAPs) are used for authorization,
the administrator is expected to delegate a ZCAP with the appropriate
format as defined in [[?ZCAP]] and as needed for the use case.
This includes appropriate values for the controller, invocation target,
and allowed actions, among other important properties.
</p>
<pre class="example nohighlight" title="VCALM Delegated Capability">
{
"@context": [
"https://w3id.org/zcap/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "urn:uuid:cdc77118-6bfa-11ec-aceb-10bf48838a41",
"parentCapability": "urn:zcap:root:https%3A%2F%2Fvcalm-instances.example.com%2Fissuers%2Fb77c9b57-c321-4d14-902c-8f442a37707d%2Fworkflows%2Fa6513552-8e5a-4efa-b36e-1fb2a8e06822%2Fexchanges",
"controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
"invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822/exchanges",
"expires": "2027-06-30T16:45:73Z",
"allowedAction": [
"write",
"read"
],
"proof": {
"type": "Ed25519Signature2020",
"created": "2026-06-30T16:45:73Z",
"verificationMethod": "did:key:z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9#z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9",
"proofPurpose": "capabilityDelegation",
"capabilityChain": [
"urn:zcap:root:https%3A%2F%2Fvcalm-instances.example.com%2Fissuers%2Fb77c9b57-c321-4d14-902c-8f442a37707d%2Fworkflows%2Fa6513552-8e5a-4efa-b36e-1fb2a8e06822%2Fexchanges"
],
"proofValue": "z3t9BCQyF21MDVYmLKc9zbLreqx4wBtQnUsd5aqyoWS5FfhapRz7QjPNLcgKAornUVmJR4ZjbGpuxRFnffxX1ZjtF"
}
}
</pre>
<p>
The `read` action enables operations that do not create or update resources in
the system to be performed on the provided path, or on any path containing the
provided path as a prefix, as permitted by `invocationTarget` and `allowedAction`
in the ZCAP. The `write` action enables operations that create and/or update
resources in the system to be performed on the provided path, or on any path
that contains the provided path as a prefix, as permitted by `invocationTarget`
and `allowedAction` in the ZCAP. To enforce the principle of
least privilege, implementers are expected to apply the following best practices:
</p>
<ol>
<li>
Ensure that ZCAPs identify a specific URL that references resources via the `invocationTarget` property
and the client that is authorized to access those resources via the `controller` property.
This enables the ZCAP to be pinned to a particular client and server (along with its resources).
Example `invocationTarget` value: `https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822`.
Example `controller` value: `did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG`.
</li>
<li>
Refer to Section [[[#component-overview]]] to determine which `invocationTarget`
and `allowedAction` values to include in ZCAPs distributed to clients,
based on the HTTP method
(e.g., `GET` -> `read`, `POST` -> `write`) and the expected caller
of the API endpoint of interest.
</li>
</ol>
<p>
Examples of valid delegated capability subsets are shown below:
</p>
<ul>
<li>
<h4>
Allow a client controller to update or retrieve the configuration
of a particular workflow instance
(a ZCAP with this subset is expected to be distributed to an administrator)
</h4>
<pre title="Update or Retrieve Workflow Configuration">
{
...
"controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
"invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822",
"allowedAction": [
"write",
"read"
],
...
}
</pre>
</li>
<li>
<h4>
Allow a client controller to create exchanges or retrieve the state of any exchange
from a particular workflow instance
(a ZCAP with this subset is expected to be distributed to a coordinator)
</h4>
<pre title="Create Exchange or Retrieve Exchange State">
{
...
"controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
"invocationTarget": "https://vcalm-instances.example.com/workflows/a6513552-8e5a-4efa-b36e-1fb2a8e06822/exchanges",
"allowedAction": [
"write",
"read"
],
...
}
</pre>
</li>
<li>
<h4>
Allow a client controller to access the API endpoint for credential issuance
on the issuer instance identified in the ZCAP
(a ZCAP with this subset is expected to be distributed to an issuer coordinator or
a workflow service)
</h4>
<pre title="Issue Credential">
{
...
"controller": "did:key:z6MknBxrctS4KsfiBsEaXsfnrnfNYTvDjVpLYYUAN6PX2EfG",
"invocationTarget": "https://vcalm-instances.example.com/issuers/b77c9b57-c321-4d14-902c-8f442a37707d/credentials/issue",
"allowedAction": [
"write"
],
...
}
</pre>
</li>
</ul>
</section>
<section class="notoc">
<h4>OAuth 2.0</h4>
<p>
If the OAuth 2.0 Authorization Framework [[?RFC6749]] is used for authorization,
the access tokens used by clients are expected to be OAuth 2.0 Bearer Tokens [[RFC6750]] or
any other valid OAuth 2.0 token type. Any valid OAuth 2.0 grant type can be used
to request the access tokens.
</p>
<table class="simple">
<thead>