-
Notifications
You must be signed in to change notification settings - Fork 0
/
consentAPI.yaml
264 lines (226 loc) · 9.23 KB
/
consentAPI.yaml
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
openapi: 3.1.0
info:
version: 1.0.0
title: Consent
# yamllint disable rule:indentiation
description: |
# Zustimmungs-API (deutsch)
**** Deutsch (for English see below) ****
Mit dem Zustimmungs-API kann eine Applikation abfragen, für welche Daten der Benutzer
ihr Zugriffsrechte erteilt hat.
Möchte eine Applikation über das OpenPK-API auf Pensionskassendaten zugreifen, so muss
sie zuerst einen interaktiven UI-Flow auslösen, der direkt zwischen der versicherten Person
und der Pensionskasse abläuft. Dabei wird sich die versicherte Person gegenüber der
Pensionskasse authentisieren und der Applikation die Zustimmung erteilen, auf ihre Daten
zuzugreifen.
Die Pensionskasse kann den Zugriff entweder *pro Objekt*, also für die Personendaten und
die Vorsorgedaten separat, lösen, oder *global*, d.h. die versicherte Person erteilt einer
Applikation den Zugriff auf alle ihre Daten. Es ist möglich, dass nur der Zugriff auf die
Vorsorgedaten, nicht aber auf die Personendaten erteilt wird.
Zum Abschluss des UI-Flows werden Zugriffstoken an die Applikation übergeben, mit denen
sie im Namen der versicherten Person auf das OpenPK-API zugreifen kann. Mit den Tokens
kann der Zugriff auch offline erfolgen, d.h. unabhängig davon, ob der Benutzer die
Applikation gerade nutzt oder nicht.
Nachdem der UI-Flow abgeschlossen ist, frägt die Applikation über das Zustimmungs-API ab,
welche Rechte die versicherte Person der Applikation eingeräumt hat. Dabei erhält sie auch
die IDs der relevanten Objekte/Ressourcen. Diese IDs werden benötigt, um Anfragen für die
anderen APIs zu erstellen.
Die gelieferten IDs können beliebige technische IDs sein (für die maximale Länge und
erlaubten Zeichen siehe weiter unten), aber sie müssen stabil sein, d.h. sie dürfen sich
über die Zeit nicht ändern. Applikationen können und sollen sie speichern.
Eine Pensionskasse stellt ihren Versicherten auch einen Weg zur Verfügung, über den sie
einer Applikation die Rechte wieder entziehen kann.
# Consent API (English)
**** English (für Deutsch siehe weiter oben) ****
Using the Consent API applications can query what access rights the user has granted to
the application.
Before an application can use the OpenPK API for a particular user, it must initiate an
interactive UI flow conducted directly between the insured person and the pension fund.
As part of the flow the insured person will authenticate itself and grant consent to
the application to access his/her pension fund data.
The pension fund can implement grants *at object level*, i.e. separately for person data
and provision data, or *globally*, i.e. the insured person grants access to all data. It is
possible to only grant access to the provision data but not to the person data.
At the end of the UI flow, the application is given access tokens that are required
to use the OpenPK APIs on behalf of the insured person. Using the tokens, offline API
access is possible as well, i.e. API access is possible even if the user is not using
the application at the same time.
After the UI flow has concluded, the application uses the Consent API to query what
permission it has been granted by the user. As part of the reply the application will
also receive the IDs of relevant objects/resources. The IDs are required to construct
requests for the other OpenPK APIs.
The object IDs can be arbitrary technical IDs (for maximum length and allowed characters
see below), but they must be stable, i.e. they may not change over time. Applications
can and should store these IDs.
A pension fund will provide means to the insured persons to revoke the granted consents.
# yamllint enable rule:indentiation
contact:
email: info@common-api.ch
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://openpk.ch/v1
externalDocs:
description: Find out more about SFTI API specifications
url: https://www.common-api.ch
tags:
- name: consent
description: Consent information.
security:
- bearerAuthentication: []
paths:
/users/me:
get:
summary: Get granted consents
description: |
Gets the consents the user (insured person) has granted to the calling application.
The consent is managed separately for each person and each policy.
For each object, the user may have granted the right view the data
or view and change it.
operationId: getUsersMe
tags:
- consent
responses:
'200':
description: Granted consent details
content:
application/json:
schema:
$ref: '#/components/schemas/Consents'
examples:
twoPolicies:
summary: Insured person with two policies
value:
personGrant:
personId: '93816732'
personAccessRight: read-only
policyGrants:
- policyId: '132559379'
policyAccessRight: read-only
- policyId: '165978481'
policyAccessRight: read-only
'400':
$ref: '#/components/responses/standard400'
'401':
$ref: '#/components/responses/standard401'
components:
schemas:
Consents:
type: object
description: Consent details (accessible object, access rights).
properties:
personGrant:
$ref: '#/components/schemas/PersonGrant'
policyGrants:
type: array
description: |
List of policies and associated access rights.
Policies that have not been granted access are omitted from the list.
items:
$ref: '#/components/schemas/PolicyGrant'
PersonGrant:
type: object
description: |
Granted consent details for person data.
It is only provided, if access to person data has been granted.
properties:
personId:
$ref: '#/components/schemas/PersonId'
personAccessRight:
$ref: '#/components/schemas/ObjectAccessRight'
PolicyGrant:
type: object
description: Granted consent details for policy data.
properties:
policyId:
$ref: '#/components/schemas/PolicyId'
policyAccessRight:
$ref: '#/components/schemas/ObjectAccessRight'
ObjectAccessRight:
type: string
description: |
Access right for object:
* `read-only` - View object data
* `change` - View and change object data
enum:
- read-only
- change
examples:
- read-only
PersonId:
type: string
pattern: '^[A-Za-z0-9_\-.~]{1,64}$'
description: Technical ID of insured person used in API calls.
examples:
- JohnDoe_1234
PolicyId:
type: string
pattern: '^[A-Za-z0-9_\-.~]{1,64}$'
description: Technical ID of policy used in API calls.
examples:
- Pol_56789-2024
# ---- Common Error Response ----
CommonErrorResponse:
title: Common Error Response
type: object
description: Common Error Response.
properties:
type:
$ref: '#/components/schemas/CommonErrorType'
title:
type: string
description: The error title.
examples:
- This is the general problem description
detail:
type: string
description: Details about the error.
examples:
- Detailed problem description with respect to the current request, e.g., invalid account number format
instance:
type: string
description: Instance of the error.
examples:
- path/to/corresponding/resource
CommonErrorType:
title: Common Error Type
type: string
description: Error Types for commonErrorResponse.
enum:
- /problems/INVALID_PAYLOAD
- /problems/MALFORMED_PAYLOAD
- /problems/INVALID_TOKEN
- /problems/EXPIRED_TOKEN
- /problems/INSUFFICIENT_PRIVILEGES
- /problems/NO_ACCESS_TO_RESOURCE
- /problems/RESOURCE_DOES_NOT_EXIST
- /problems/RESOURCE_NOT_READY
- /problems/RESOURCE_TOO_LARGE
- /problems/WRONG_METHOD
- /problems/OPERATION_NOT_ALLOWED
- /problems/TECHNICAL_ERROR
- /problems/NOT_IMPLEMENTED
- /problems/SERVICE_UNAVAILABLE
examples:
- /problems/TECHNICAL_ERROR
securitySchemes:
bearerAuthentication:
type: http
description: Bearer access token in HTTP header.
scheme: bearer
bearerFormat: JWT
# ---- Responses - Standard Errors Common Data Model ----
responses:
standard400:
description: Some of the input is incomplete or invalid for starting a request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/CommonErrorResponse'
standard401:
description: Access token is missing or invalid.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/CommonErrorResponse'