-
Notifications
You must be signed in to change notification settings - Fork 47
/
Copy pathindex.html
1509 lines (1374 loc) · 60.2 KB
/
index.html
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>Verifiable Credentials API v0.3</title>
<meta content='text/html; charset=utf-8' http-equiv='Content-Type'>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check
them out in the same tree and use relative links so that they'll work
offline.
-->
<script class="remove"
src="https://unpkg.com/browse/jquery/dist/jquery.min.js"></script>
<script class="remove"
src="https://www.w3.org/Tools/respec/respec-w3c"></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/digitalbazaar/[email protected]/dist/main.js"></script>
<script class="remove"
src="https://cdn.jsdelivr.net/gh/digitalbazaar/[email protected]/dist/main.js"></script>
<script class="removeOnSave"
src="https://unpkg.com/reqlist/lib/reqlist.js"></script>
<link class="removeOnSave" rel="stylesheet" type="text/css"
href="https://unpkg.com/reqlist/lib/reqlist.css" />
<script class='remove' src="./common.js"></script>
<script class='remove' src="./respec-oas.js"></script>
<script class="remove" type="text/javascript">
var respecConfig = {
// the W3C WG and public mailing list
group: "credentials",
wgPublicList: "public-credentials",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "vc-api",
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "CG-DRAFT",
// W3C Candidate Recommendation information
//crEnd: "2021-05-04",
//implementationReportURI: "https://w3c.github.io/vc-api-test-suite/",
// Editor's Draft URL
edDraftURI: "https://w3c-ccg.github.io/vc-api/",
// subtitle for the spec
subtitle: "An HTTP API for Verifiable Credentials lifecycle management",
// if you wish the publication date to be other than today, set this
//publishDate: "2019-11-07",
// 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: ccg.localBiblio,
xref: "web-platform",
github: {
repoURL: "https://github.com/w3c-ccg/vc-api/",
branch: "main"
},
includePermalinks: false,
// Uncomment these to use the respec extension that generates a list of
// normative statements:
preProcess: [window.respecMermaid.createFigures],
postProcess: [injectOas, restrictRefs],
lint: {
"no-unused-dfns": false
},
// list of specification editors
editors: [{
name: "TBD"
}],
// list of specification authors
authors: []
};
</script>
<style>
pre .highlight {
font-weight: bold;
color: green;
}
pre .comment {
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;
}
table.column-width-50 td {
width: 50%;
}
</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 highly experimental and changing rapidly. Implementation
in non-experimental systems is discouraged unless you are participating in
the weekly meetings that coordinate activity around this specification.
</p>
<p>
Comments regarding this document are welcome. Please file issues
directly on <a href="https://github.com/w3c-ccg/vc-api/issues/">GitHub</a>,
or send them
to <a href="mailto:[email protected]">[email protected]</a> (
<a href="mailto:[email protected]?subject=subscribe">subscribe</a>,
<a href="https://lists.w3.org/Archives/Public/public-credentials/">archives</a>).
</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 <a>verifiable credentials</a>, 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 <a>verifiable credentials</a>. Knowing that
a particular architecture has been vetted is also beneficial for architects that
do not specialize in <a>verifiable credentials</a>. 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
<a>verifiable credential</a> interaction, such as an API that is used to
communicate presentations between a Holder and a Verifier. In order to
achieve protocol interoperability in <a>verifiable credentials</a> 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 <a>verifiable credentials</a> as well as updating their status.
</li>
<li>
<a href="#verifying"></a> specifies the APIs for verifying both
<a>verifiable credentials</a> and verifiable presentations.
</li>
<li>
<a href="#presenting"></a> defines APIs for generating and deriving
<a>verifiable presentations</a> within a trust domain, as well as
exchanging <a>verifiable presentations</a> 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>
<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 VC 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="VC API Components of Coordinators, Services, and Admin for Issuers, Verifiers, and Holders">
<figcaption style="text-align: center;">
VC API Components. Arrows indicate initiation of flows.
</figcaption>
</figure>
<p>
Any given VC API 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>
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 the VC API, each component satisfies all of
its required functionality as a whole, regardless of deployment
architecture.
</p>
<p>
We define these components as follows:
</p>
<section>
<h3>Coordinators</h3>
<p>
<strong>Issuer Coordinator • Verifier Coordinator • Holder Coordinator </strong>
</p>
<p>
Coordinators execute 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 VC ecosystem.
</p>
<p>
Coordinators may or may not provide a visual user interface, depending on the
implementation. Pure command-line or continuously running services may
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>
The Issuer Coordinator 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
App and back-end services are out of scope for the VC-API. The Issuer Coordinator
drives the Issuer service.
</p>
<p>
The Verifier Coordinator communicates with a Verifier service to first check
authenticity and timeliness of a given VC or VP, then Applies the
Verifier's business rules before ultimately accepting or rejecting that VC
or VP. Such business rules may include evaluating the Issuer of a
particular claim or simply checking a configured allow-list. The Verifier
App exposes an API for submitting VCs to the Verifier per the Verifier's
policies. For example, the Verifier Coordinator may only accept VCs from current
users of the Verifier's other services. These rules typically require
bespoke integration with the Verifier's existing back-end.
</p>
<p>
The Holder Coordinator executes the business rules for Approving the flow of
credentials under the control of the Holder, from Issuers to Verifiers. In
several deployments this means exposing a user interface that gives
individual Holders a visual way to authorize or Approve VC storage or
transfer. Some functionality of the Holder Coordinator is commonly referred to as
a wallet. In the VC API, the Holder Coordinator initiates all flows. They request
VCs from Issuers. They decide if, and when, to share those VCs with
Verifiers. Within the VC API, there is no way for either the Issuer or the
Verifier to initiate a VC transfer. 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 VCs, even if only at the step
of authorizing the transfer. However, many VCs are about organizations,
not individuals. How individuals using Holder Coordinators related to
organizations, and in particular, how organizational credentials are
securely shared with, and presented by, (legal) agents of those
organizations is not yet specified as in scope for the VC API.
</p>
</section>
<section>
<h3>Services</h3>
<p>
<strong>Issuer Service • Verifier Service • Holder Service </strong>
</p>
<p>
Services provide generic VC API functionality, driven by its associated
App. Designed to enable infrastructure providers to offer VC capability
through Software-as-a-Service. All services expose network endpoints to
their authorized Coordinators, which are themselves operating on behalf of the
associated role. Although deployed services MAY provide their own HTML
interfaces, such interfaces are out of scope for the VC API. Only the
network endpoints of services are defined herein.
</p>
<p>
The Issuer Service takes requests to issue VCs from authorized Issuer Coordinators
and returns well-formed, signed Verifiable Credentials. This service MUST
have access to private keys (or key services which utilize private keys)
in order to create the proofs for those VCs. The API between the Issuer
service and its associated key service is believed to be out of scope for
the VC API, but may be addressed by WebKMS or similar specifications.
</p>
<p>
The Verifier service 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 VC; leaving the Verifier Coordinator to finish Applying any business rules needed.
</p>
<p>
The Holder service takes requests to create Verifiable Presentations
from an optional set of VCs and returns well-formed, signed Verifiable
Presentations containing those VCs. These VPs are used with Issuers to
demonstrate control over DIDs prior to issuance and with Verifiers to
present specific VCs.
</p>
</section>
<section>
<h3>Status Service</h3>
<p>
The Status Service provides a privacy-preserving means for publishing
and checking the status of any Verifiable Credentials issued by the
Issuer. Verifier services use the Issuer's status endpoint (as
specified in each revocable verifiable credential) to check the
timeliness of a given VC as part of verification.
</p>
</section>
<section>
<h3>Storage Services</h3>
<p>
<strong>Storage Service (Issuer) •Storage Service
(Verifier) • Storage Service (Holder)
</strong>
</p>
<p>
Each actor in the system is expected to store their own verifiable
credentials, as needed. Several known implementations use secure data
storage such as encrypted data vaults for storing the Holder's VCs and
use cryptographic authorizations to grant access to those VCs to
Verifier Coordinators, as directed by the Holder. In-browser retrieval of such
stored credentials can enable web-based Verifier Coordinators 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 the VC 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>
</section>
<section>
<h3>Workflow Service</h3>
<p>
The Workflow Service 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 authorized
access to those exchanges to any party.
</p>
</section>
<section>
<h3>Admin</h3>
<p><strong>Issuer Admin • Holder Admin • Verifier Admin</strong></p>
<p>
The Admin component 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
may use JSON files to drive a semi-automated Issuer. Others might
expose HTML pages. We expect different Coordinators and Services to compete on
the power, ease, and flexibility of their administration and
therefore, as of this writing, we anticipate Admin functionality to be
out of scope for the VC API. However, we actually believe that to the
extent we can standardize configuration setting across
implementations, the more substitutable each component.
</p>
</section>
<section>
<h3>Summary</h3>
<p>
Based on this architectural thinking, we may want to frame the VC 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 VC 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 the VC API while deferring
the definition of how those elements work to specification already in
development as well as those yet to be written.
</p>
</section>
</section>
<section id="conformance">
<p>
</p>
<p>
A conforming <dfn>VC API client</dfn> is ...
</p>
<p>
A conforming <dfn>VC API server</dfn> is ...
</p>
</section>
</section>
<section class="informative">
<h2>Terminology</h2>
<div data-include="https://w3c.github.io/vc-data-model/terms.html">
</div>
</section>
<section>
<h2>The VC API</h2>
<section>
<h3>Base URL</h3>
<p>
There are no restrictions put on the base URL location of the implementation.
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., <code>example.com</code>), a
subdomain (e.g., <code>api.example.com</code>), or a path within that host (e.g.,
<code>example.com/api</code>).
</p>
</section>
<section>
<h3>Authorization</h3>
<p>
The VC API can be deployed in a variety of networking environments which
might contain hostile actors. As a result, conforming <a>VC API servers</a>
require conforming <a>VC API clients</a> 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, the VC API is agnostic
regarding authorization mechanism.
</p>
<p>
The VC 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 a VC API call include <a href="https://chapi.io/">CHAPI</a> (the
<a href="https://chapi.io/">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>
<h4>Forbidden Authorization</h4>
<p>
Requests to the VC 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>
<h4>OAuth 2.0</h4>
<p>
If the OAuth 2.0 Authorization Framework [[RFC6749]] is utilized for authorization,
the access tokens utilized by clients MAY be OAuth 2.0 Bearer Tokens [[RFC6750]]
or any other valid OAuth 2.0 token type. Any valid OAuth 2.0 grant type MAY be used
to request the access tokens. However, OAuth 2.0 MUST be implemented in the following
way:
</p>
<p>
OAuth2 tokens for this purpose have an audience of the particular issuer instance,
e.g., `origin/issuers/zc612332f3`.
</p>
<p>
The scopes are generalized to read/write actions on particular endpoints:
</p>
<ul>
<li>
`read:/` would allow reading on any API on a particular instance.
</li>
<li>
`write:/` would allow writing on any API on a particular instance.
</li>
</ul>
<p>
`write:/credentials/issue` would only allow writing to that particular API.
</p>
<p>
Other authorization mechanisms that support delegation might be defined in the future.
</p>
</section>
</section>
<section>
<h3>Service Instances</h3>
<p>
Service configuration is determined by administrators on per instance basis.
Instance configuration can include, but is not limited to, credential format, key options, credential status mechanisms, and/or credential templates.
Administrators are expected to configure service instances such that `options` included in client requests cannot result in incorrect action or problematic responses by the service.
</p>
<p>
A coordinator instance can have access to multiple service instances in order to support different use cases.
Runtime discovery of service instance configuration is not supported by the VC API as services are expected to be known by the coordinator at the time of coordinator deployment.
</p>
</section>
<section>
<h3>Options</h3>
<p>
Some of the endpoints defined in the following sections accept an `options` object.
All properties of the `options` object are OPTIONAL when configuring each instance,
as these properties are intended to meet per-deployment needs that might vary.
Thus, any given instance configuration MAY prohibit client use of some `options`
properties in order to prevent clients from passing certain data to that instance.
Likewise, an instance configuration MAY require that clients include some `options`
properties.
</p>
<h4>Options Extensibility</h4>
<p>
Implementations MAY extend an `options` object with additional properties.
</p>
<p>
As extension properties are implementation specific, they ought not be mandatory.
This is to maintain interoperability by avoiding clients needing to be modified to use a specific implementation.
</p>
<p>
When adding an extension `options` property, consider whether providing optionality to clients is necessary.
If not, using instance configuration to vary API functionality might be a preferable approach.
</p>
</section>
<section>
<h3>Content Serialization</h3>
<p>
All entity bodies in requests and responses sent to or received from the API endpoints defined by this specification MUST be serialized as JSON and include the `Content-Type` header with a media type value of `application/json`.
</p>
</section>
<section>
<h3>Handling Unknown Options and Data</h3>
<p>
Many of the endpoints defined in the following sections receive data and options in request bodies.
</p>
<p>
Implementations MUST throw an error if an endpoint receives data, options, or option values that it
does not understand or know how to process.
</p>
</section>
<section>
<h3>API Component Overview</h3>
<p>
This section gives an overview of all endpoints in the VC-API by the component the endpoint is expected be callable from.
If a component does not have a listing below it means the VC-API does not currently specify any endpoints for that component.
</p>
<h4>Issuer Coordinator</h4>
<p>
Below are all endpoints expected to be exposed by the Issuer Coordinator, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials"></table>
<h4>Issuer Service</h4>
<p>
Below are all endpoints expected to be exposed by the Issuer Service, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials/issue /credentials /credentials/{id}"></table>
<h4>Status Service</h4>
<p>
Below are all endpoints expected to be exposed by the Status Service, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials/status"></table>
<h4>Verification Service</h4>
<p>
Below are all endpoints expected to be exposed by the Verification Service, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials/verify /presentations/verify /challenges"></table>
<h4>Holder Service</h4>
<p>
Below are all endpoints expected to be exposed by the Holder Service, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials/derive /presentations/prove /presentations /presentations/{id}"></table>
<h4>Workflow Service</h4>
<p>
Below are all endpoints expected to be exposed by the Workflow Service, along with the component
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/workflows /workflows/{localWorkflowId} /workflows/{localWorkflowId}/exchanges /workflows/{localWorkflowId}/exchanges/{localExchangeId}"></table>
</section>
<section>
<h3>Issuing</h3>
<p>
The following APIs are defined for issuing a Verifiable Credential:
</p>
<table class="simple api-summary-table"
data-api-path="/credentials /credentials/{id}
/credentials/issue /credentials/status"></table>
<section>
<h4>Issue Credential</h4>
<p>
</p>
<p class="note" title="Issued credential media types">
An `EnvelopedVerifiableCredential` can be returned in the `IssueCredentialSuccess` response
in order to issue credentials with a media type other than `application/vc`,
such as `application/vc+sd-jwt`.
</p>
<div class="api-detail"
data-api-endpoint="post /credentials/issue"></div>
</section>
<section>
<h4>Get Credentials</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="get /credentials"></div>
</section>
<section>
<h4>Get a Specific Credential</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="get /credentials/{id}"></div>
</section>
<section>
<h4>Update Status</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="post /credentials/status"></div>
</section>
</section>
<section>
<h3>Verifying</h3>
<p>
The following APIs are defined for verifying a Verifiable Credential:
</p>
<table class="simple api-summary-table"
data-api-path="/credentials/verify /presentations/verify /challenges"></table>
<section>
<h4>Verify Credential</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="post /credentials/verify"></div>
</section>
<section>
<h4>Verify Presentation</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="post /presentations/verify"></div>
</section>
<section>
<h4>Create Challenge</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="post /challenges"></div>
<p>
The instance should create a challenge for use during verification, and track the number of times the challenge has been passed to verification endpoints as `options.challenge`.
</p>
</section>
</section>
<section>
<h3>Presenting</h3>
<p>
The following APIs are defined for presenting a Verifiable Credential:
</p>
<table class="simple api-summary-table"
data-api-path="
/credentials/derive /presentations
/presentations /presentations/{id}
/exchanges/ /exchanges/{exchange-id} /exchanges/{exchange-id}/{transaction-id}"
></table>
<p class="advisement">
The URL path values <code>exchange-id</code> and <code>transaction-id</code> are
meaningful to the server but are opaque to the client. While some server
implementations might use values that happen to be human-readable, clients are
strongly advised to not assign semantics to any human-readable values.
</p>
<section>
<h4>Derive Credential</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="post /credentials/derive"></div>
</section>
<section>
<h4>Create Presentation</h4>
<p>
</p>
<p class="note" title="Presentation media types">
An `EnvelopedVerifiablePresentation` can be returned in the response
in order to create presentations with a media type other than `application/vp`,
such as `application/vp+jwt`.
</p>
<div class="api-detail"
data-api-endpoint="post /presentations"></div>
</section>
<section>
<h4>Exchange Discovery</h4>
<p>
Discovery is an optional call for the Holder Coordinator to ensure the Holder Coordinator can support
the exchange protocol requirements before calling the endpoint. Coordinators SHOULD support
the exchange discovery endpoint.
</p>
<div class="api-detail"
data-api-endpoint="post /exchanges/"></div>
</section>
<section>
<h4>Get Presentations</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="get /presentations"></div>
</section>
<section>
<h4>Get a Specific Presentation</h4>
<p>
</p>
<div class="api-detail"
data-api-endpoint="get /presentations/{id}"></div>
</section>
</section>
<section>
<h3>Workflows and Exchanges</h3>
<p>
A VC API workflow defines a particular set of steps for exchanging verifiable
credentials between two parties across a trust boundary. Each step can involve
the issuance, verification, transmission, or presentation of verifiable
credentials. Examples of VC API workflows include, but are not limited to:
</p>
<ul class="bullet">
<li>
Issuing an employee membership credential to an employee who has logged in to a
coordinator website.
</li>
<li>
Issuing a vehicle title credential after receiving a presentation of a
driver's license credential.
</li>
<li>
Verification of the presentation of a permanent resident credential.
</li>
<li>
Receipt of one or more newly-issued single-use proof of age credentials.
</li>
</ul>
<p>
Workflow instances are expected to be created by administrators, for use with,
for example, coordinator websites. A workflow instance is created by performing
an HTTP POST to the workflow service's `/workflows` endpoint. The HTTP request
body includes the configuration for the workflow instance. This includes, but
is not limited to, information about the steps that define the workflow and any
credential templates that will be used to issue verifiable credentials. The
steps that define the workflow might also be templates, enabling additional
flexibility. If a workflow involves the issuance of verifiable credentials, or
the verification of presentations or credentials, then the workflow instance
configuration can include authorization capabilities to use one or more VC API
issuer and/or verification services.
</p>
<p>
Once a workflow instance exists, authorization to create and query particular
workflow interactions, called VC API exchanges, can be given to coordinators.
</p>
<p>
A VC API exchange represents a particular interaction based on a given VC API
workflow. The interaction will take place between an exchange client and the
workflow service. Exchanges are expected to be transitory, only existing as
long as the interaction takes to complete. The workflow service stores state
information about each exchange such as whether the exchange is pending,
active, or complete, as well as the current step in the workflow, any
workflow-specific variables and data, and any verifiable presentations and
credentials received while the exchange executes.