forked from APNF/man-openapi
/
apnf-man-platform-openapi-gco.yaml
494 lines (445 loc) · 23.7 KB
/
apnf-man-platform-openapi-gco.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
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
openapi: 3.0.3
info:
title: API for the emulated MAN GCO endpoints
version: 1.0.1
license:
name: CC-BY-SA-4.0
url: https://creativecommons.org/licenses/by-sa/4.0/legalcode
contact:
email: api-support@metaswitch.com
url: https://www.metaswitch.com/
description: |
# API for the emulated MAN GCO endpoints
This is the OpenAPI specification for the GCO endpoints, as provided by APNF under the CC-BY-SA-4.0 license,
and edited by Metaswitch (a Microsoft company) under the same license. These edits remove several endpoints,
methods, request and response parameters, and response codes from the APNF version for Metaswitch's client-side
use-case, and make minor adjustments to the description fields for nicer output with the Swagger OpenAPI tool.
There follows information retained from the original API definition. Much of the function described is not
present in this version of the API so may not be accurate for implementations based on this file.
# Introduction
Welcome to the APNF MAN platform GCO (*Gestionnaire des Certificats Opérateurs*) API reference.
The APIs listed in this reference provide functionalities for service providers to create and
manage the STI certificates to be used for signing their SIP telephone calls per the STIR SHAKEN
protocol, along with functionalities to manage access to the MAN platform.
Each provider registered with the APNF may request an access to the MAN platform and therefore these APIs.
## Authentication
All APIs listed in this document require the API client to be authenticated.
The authentication process relies on OAuth 2.0 protocol, where an access token needs
to be passed to the API request as a JSON Web TOKEN using the Bearer `Authorization` header.
```
Authorization: Bearer <JWT>
```
Refer to the *MAN Platform Authorization API Reference* on how to generate access tokens. Note that in order to
request an access token, you will first need to create an **API credential** as described in this reference.
## Requests & Headers
- A Bearer `Authorization` header is required, where the Bearer token shall be set with the access token generated by the MAN platform authorization API.
- A `X-Request-Id` header can be provided with an uuid. If provided, this header will be returned in the
`X-Response-Id` response header.
## Responses & Headers
Unless explicitly specified, all responses will use JSON for the response body format.
The `Content-Type` header will be included in all responses to make the type explicit.
Following headers are also included in responses:
- `Content-Type`: format of the response, if a body is included in the response.
- `Content-Length`: size in bytes of the response body, if a body is included in the response.
- `X-Response-Id`: uniquely identifies the response sent to the client. It corresponds to the `X-Request-Id`
request header if provided. Otherwise, a new value is generated,
- `X-Correlation-Id`: ID generated by the API gateway to track the request between the different services. This
value can be different from the `X-Response-Id` header.
## Dates
Unless specified, all dates exposed in this API comply with the ISO-8601 date format using UTC as the timezone.
## Common Error Codes
The following error codes can be returned:
| Error code | Description |
|:----------:|-------------------------------------------------------------------------|
| **400** | The request is malformed. |
| **401** | The authentication failed. |
| **403** | User is not allowed to access to the resource. |
| **404** | The resource does not exist. |
| **405** | The method is not allowed for the resource. |
| **406** | The format in the `Accept` header is not supported. |
| **409** | There is a conflict between the object status and the action requested |
| **415** | The format in the `Content-Type` header is not supported. |
| **429** | Too many requests have been sent by the client (see Rate Limiting). |
| **500** | An unexpected error occurred while processing the request. |
| **503** | The service is unavailable. |
## Rate Limiting
To ensure availability to all clients, concurrent accesses to this API are restricted per
below rate limiting logic:
- Each IP address is allowed to perform up to 600 calls during a period of 1 minute.
- The `GET /bpco/certificates` API method has an additional restriction, limiting calls to 1 per minute.
- Any additional call will be rejected by the API using a 429 "TOO_MANY_REQUESTS" error code
# References
Additional API references are also available, covering other functionalities:
- **MAN Platform Authentication API Reference**, providing the APIs to create access tokens require to authenticate against the APIs listed in this document.
- **MAN Platform BPCO API Reference**, listing APIs published as part of the BPCO (Base Publique des Certificats Opérateurs), the MAN platform public access service used to access STI certificates.
# History
**1.6.0** - 2023/12/13
- (Certificates) PATCH /certificates/{certificate_id} - Add constraints for expired certificates
- (Certificates) POST /certificates/{certificate_id} - Add 409 HTTP status case
- (Certificates) GET /certificates/export - New endpoint to export certificates as CSV
- (Providers) GET /providers/{provider_id} - New `legal_administrator` property to provide provider current legal administrator user.
- (Providers) GET /providers - Removed `verified`, `verified_at` and `verified_status` filters as never implemented
- (Providers) GET /providers/{provider_id}/bypass_token - Add 415 HTTP status case
- (Providers) PATCH /providers/{provider_id} - New `legal_administrator` property to change provider legal administrator user
- (Providers) PATCH /providers/{provider_id} - Allow `opts_contracts` property to be edited by MANAGER users
- (Providers) Add `BypassTokenId` schema
- (Providers) Update `BypassToken` schema to add `BypassTokenId` reference and specify required properties
- (Providers) Update `bypass_token` property in `Provider` schema
- (Providers) Remove `domains_allowed` mentions from `ProviderCreationRequest` schema and examples as property has been removed since 1.3.0 release
- (Providers) Updated `ProviderDetails` schema to add `deposit_notification_list` property and remove `last_verification` property
- (Users) GET /users - Add `created_at`, `updated_at` and `last_connected_at` properties to `UserSummaryView` schema
- (Users) GET /users - Grant API method access to the MANAGER role.
- (Users) GET /users/{user_id} - Grant API method access to the MANAGER role.
- (Users) GET /users/{user_id} - New `legal_administrator ` to see if user is legal administrator.
- (Users) POST /users – Allow APNF administrators to create provider administrator users
- (Users) PATCH /users - Allow APNF administrators to update the role of any provider user.
- (Users) POST /users/reset-credential - Rename original reset-password to enhance functionality by adding reset of OTP and resend new link of account activation.
- (BPCO) GET /bpco/certificates - Add missing `Content-Length` response header
- (Description) Fix spelling error in 'Rate limiting'
**1.5.0** - 2023/09/27
- Include in `Description` section rate limiting logic
- Add CC-BY-SA-4.0 license
**1.4.0** - 2023/06/27
- (Providers) POST /providers/{provider_id}/bypass_token - Add new API to generate a new provider bypass token
- (Providers) GET /providers/{provider_id}/bypass_token - Add new API to retrieve bypass tokens generated by the provider
- (Providers) GET /providers/{provider_id} - Add `bypass_token` property in Provider schema
**1.3.0** - 2023/06/16
- Add `servers` entries for VABF and Preproduction platforms
- (Certificates) Clarify `renewal_after` property usage
- (Certificates) Clarify `valid_to` constraints
- (Providers) Deprecate `domains_allowed` property
- (Providers) `technical_number` property cannot be edited by provider administrators
**1.2.0** - 2023/05/04
- (All) Remove `Content-Length` header for 204 and 304 responses
- (All) Update error message for 401 HTTP responses
- (All) Add 405 HTTP status case + update error message
- (All) Use different ID values depending on the object type
- (Certificates) Add new status `INVALID`
- (POST /certificates/) Add `updated_at`, `updated_by` properties to response examples
- (POST /certificates) Add `Location` header in responses
- (POST /certificates/) Test certificates cannot have the `renewal_auto` property enabled.
- (PATCH /certificates/{certificate_id}) Test certificates cannot have the `renewal_auto` property enabled.
- (POST /certificates/{certificate_id}/renew) Add constraints for revoked and invalid certificates
- (POST /certificates/{certificate_id}/renew) Test certificates cannot have the `renewal_auto` property enabled.
- (POST /certificates/{certificate_id}/renew) Clarify valid_from/valid_to property constraints
- (POST /certificates/{certificate_id}/renew) Add 409 HTTP status case for revoked certificates
- (POST /certificates/{certificate_id}/renew) Add `Location` header in responses
- (POST /certificates/{certificate_id}/revoke) Add constraints for expired, revoked and invalid certificates
- (HEAD /bpco/certificates) Remove `Content-Length` response header and body
- (GET /bpco/certificates) Add `Content-Type` header for 304 HTTP status case
- (HEAD /bpco/crl) Remove `Content-Length` response header and body
- (GET /bpco/crl) Add `Content-Type` header for 304 HTTP status case
- (Providers) New `deposit_notification_list` property in Provider object
- (Providers) Improve `domains_allowed` property description for `ProviderCreationRequest` example
- (Providers) Allow `opts_contracts` property to be edited by *ADMINISTRATOR* users
- (Users) New `/users/{user_id}/preferences` method
- (Users) Remove `/user/activate` method
**1.1.0** - 2023/01/18
- Update base URL from *https://man-plateforme.fr/api/* to *https://api.man-plateforme.fr/*
- Update BPCO API URLs from *https://man-bpco.fr/* to *https://api.man-bpco.fr/*
- Change `Certificate` component schema to change `revoked_at` property format from `integer` to `string`
- Update certificate serial number schema pattern
- Cleanup `ProviderOIDCSettings` component schema
tags:
- name: BPCO
description: |
APIs related to BPCO (Base Publique des Certificats Opérateurs), the MAN platform public access
service to STI certificates.
These APIs provide access to metadata and download facilities to objects
published in the BPCO, like STI certificates and CRLs.
paths:
/bpco/certificates:
get:
summary: Get a copy of STI certificates in BPCO
description: |
This method returns as a GZipped TAR file a copy of all the STI certificates currently published in the BPCO.
If the `since` parameter is specified, the GZipped TAR file only contains the certificates published in the BPCO or
removed from it since the date provided in the parameter.
The list of certificates removed from the BPCO are available in a `removed-certificates.csv` file included in the tarball.
A `If-Modified-Since` request header may also be specified. In that case, a **304** response is returned if no certificates
have been added or removed since the date specified in the header. This latter can be filled with the value of the
`Last-Modified` response header collected from a previous call to this API or the `HEAD /bpco/certificates` one.
**Allowed Roles**: *MAN_ADMINISTRATOR*, *ADMINISTRATOR*, *MANAGER*, *APNF*.
operationId: GetBpcoCertificatesCopy
tags:
- BPCO
parameters:
- name: since
in: query
description: |
Date in ISO-8601 format. When specified, return only the certificates added or removed since that date.
The minutes and seconds are ignored (`2022-01-17T10:12:25Z` is therefore interpreted as `2022-01-17T10:00:00Z`)
and the date cannot be older than 15 days.
required: false
schema:
type: string
format: date-time
example: '2022-01-19T10:00:00Z'
- $ref: '#/components/parameters/If-Modified-Since'
responses:
'200':
description: |
GZipped bulk certificate TAR file.
Return a GZipped TAR file which includes the certificates using the following structure:
```
|-<Service Provider Code #A>/
| |- <serial number certificat #A1>.cer
| |- <serial number certificat #A2>.cer
| `- <serial number certificat #A3>.cer
|-<Service Provider Code #B>/
| |- <serial number certificat #B1>.cer
| |- <serial number certificat #B2>.cer
|-<Service Provider Code #C>/
[...]
```
If the `since` parameter is present, a `removed-certificates.csv` file may be included at the root of the
GZipped TAR file.
When present, this file lists all certificates deleted from the BPCO since that date, using the following
format:
```ini
<Service Provider Code #A>;<serial number certificat #A4>
<Service Provider Code #B>;<serial number certificat #B3>
<Service Provider Code #C>;<serial number certificat #C2>
```
A semicolon (`;`, `U+003B`) is used between each column and a linefeed is used between each line
(`\n`, `U+000A`).
content:
application/gzip:
schema:
type: string
format: binary
headers:
Content-Length:
$ref: '#/components/headers/Content-Length'
Last-Modified:
description: Last update date of STI certificates in the BPCO. Uses HTTP-Date format (RFC 7231)
schema:
$ref: '#/components/schemas/RFC7231.HTTP-date'
'304':
description: |
No changes since supplied header value.
No changes since the date provided in the `If-Modified-Since` request header.
headers:
Last-Modified:
description: Last update date of STI certificates in the BPCO. Uses HTTP-Date format (RFC 7231)
schema:
$ref: '#/components/schemas/RFC7231.HTTP-date'
Content-Type:
$ref: '#/components/headers/Content-Type-GZip'
'400':
$ref: '#/components/responses/ErrorValidation'
'401':
$ref: '#/components/responses/ErrorNotAuthenticated'
'429':
$ref: '#/components/responses/ErrorRateLimiting'
'500':
$ref: '#/components/responses/ErrorInternal'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/bpco/crl:
get:
summary: Get a copy of the STI certificates CRL in BPCO
description: |
Get a copy of the STI certificates Certificate Revocation List (CRL) as available in the BPCO.
The API returns the CRL in DER format, with the exact same contents returned by the BPCO API `GET /crl`.
A `If-Modified-Since` request header may also be specified. In that case, a **304** response is returned
if the CRL has not been updated since the date specified in the header. This latter can be filled with the value of the
`Last-Modified` response header collected from a previous call to this API or the `HEAD /bpco/crl` one.
**Allowed Roles**: *MAN_ADMINISTRATOR*, *ADMINISTRATOR*, *MANAGER*, *APNF*.
operationId: GetBpcoCrlCopy
tags:
- BPCO
parameters:
- $ref: '#/components/parameters/If-Modified-Since'
responses:
'200':
description: |
DER formatted CRL.
The Certificate Revocation List in DER format.
content:
application/pkix-crl:
schema:
type: string
format: binary
example: |
00000000: 3082 0120 3081 c802 0101 300a 0608 2a86 0.. 0.....0...*.
00000010: 48ce 3d04 0302 3067 3111 300f 0603 5504 H.=...0g1.0...U.
00000020: 030c 0842 5043 4f20 5041 3131 0b30 0906 ...BPCO PA11.0..
00000030: 0355 0406 1302 4652 312a 3028 0603 5504 .U....FR1*0(..U.
00000040: 0a0c 2142 6173 6520 6465 7320 4365 7274 ..!Base des Cert
00000050: 6966 6963 6174 7320 4f70 c383 c2a9 7261 ificats Op....ra
00000060: 7465 7572 3119 3017 0603 5504 0b0c 1050 teur1.0...U....P
00000070: 6f6c 6963 7920 4175 7468 6f72 6974 7917 olicy Authority.
00000080: 0d32 3230 3730 3431 3235 3032 305a 170d .220704125020Z..
00000090: 3232 3038 3033 3132 3530 3230 5aa0 3030 220803125020Z.00
000000a0: 2e30 1f06 0355 1d23 0418 3016 8014 097a .0...U.#..0....z
000000b0: 34d8 9663 a43e 0250 9294 9de2 de31 8135 4..c.>.P.....1.5
000000c0: 3c8a 300b 0603 551d 1404 0402 0210 0030 <.0...U........0
000000d0: 0a06 082a 8648 ce3d 0403 0203 4700 3044 ...*.H.=....G.0D
000000e0: 0220 58da 50e6 2670 a7e4 413d bb9d c193 . X.P.&p..A=....
000000f0: e0c0 3852 0138 1bd0 73fc 04fa 7328 952b ..8R.8..s...s(.+
00000100: e169 0220 1110 3e86 450b f0db 4345 80c9 .i. ..>.E...CE..
00000110: b12e d905 9f72 051a e02d fd3d 67d7 4ce2 .....r...-.=g.L.
00000120: b92f e546 ./.F
headers:
Last-Modified:
description: Last update date of STI certificates CRL in the BPCO. Uses HTTP-Date format (RFC 7231).
schema:
$ref: '#/components/schemas/RFC7231.HTTP-date'
Content-Length:
description: Size in bytes of the DER contents provided in the response.
schema:
type: integer
example: 311
'304':
description: |
No changes since supplied header value.
No changes since the date provided in the `If-Modified-Since` request header
headers:
Last-Modified:
description: Last update date of STI certificates CRL in the BPCO. Uses HTTP-Date format (RFC 7231).
schema:
$ref: '#/components/schemas/RFC7231.HTTP-date'
Content-Type:
$ref: '#/components/headers/Content-Type-Pkix-Crl'
'400':
$ref: '#/components/responses/ErrorValidation'
'401':
$ref: '#/components/responses/ErrorNotAuthenticated'
'429':
$ref: '#/components/responses/ErrorRateLimiting'
'500':
$ref: '#/components/responses/ErrorInternal'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security:
- access_token: []
components:
securitySchemes:
access_token:
type: http
description: |
APIs need to provide an access token created using the MAN Platform Authorization API and which complies with OpenID Connect protocol.
Refer to the *MAN platform authorization API Reference* on how to generate these access tokens.
scheme: bearer
bearerFormat: JWT
responses:
ErrorValidation:
description: |
Input validation failed.
Returned when the request input validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPayloadError'
example:
code: BAD_REQUEST
ErrorNotAuthenticated:
description: |
Not authenticated.
Returned when the client authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPayloadError'
example:
code: UNAUTHORIZED
message: The authentication failed.
headers:
Content-Length:
$ref: '#/components/headers/Content-Length'
ErrorRateLimiting:
description: |
Too many requests.
Returned when too many requests have been sent by the client in a certain amount of time.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPayloadError'
example:
code: TOO_MANY_REQUESTS
message: Rate limit is exceeded.
headers:
Content-Length:
$ref: '#/components/headers/Content-Length'
ErrorInternal:
description: |
Internal error.
Returned when an unexpected error occurred while processing the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPayloadError'
example:
code: INTERNAL_SERVER_ERROR
message: An unexpected error occurred while processing the request.
headers:
Content-Length:
$ref: '#/components/headers/Content-Length'
ServiceUnavailable:
description: |
Service unavailable.
Returned when the service is unavailable (e.g. maintenance mode) and cannot process the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPayloadError'
example:
code: SERVICE_UNAVAILABLE
message: The service is currently unavailable.
headers:
Content-Length:
$ref: '#/components/headers/Content-Length'
schemas:
RFC7231.HTTP-date:
type: string
description: Date format as defined in RFC7231, section 7.1.1.1.
pattern: ^((Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT)$
example: Mon, 17 Jan 2022 10:12:25 GMT
ApiPayloadError:
type: object
description: Data model for error responses.
required:
- code
- message
properties:
code:
type: string
maxLength: 64
description: Error code. Shall be capitalized with underscores.
message:
type: string
maxLength: 1024
description: Message providing more details and context for the error that occurred.
parameters:
If-Modified-Since:
name: If-Modified-Since
in: header
description: Date in HTTP-Date format (RFC 7231).
required: false
schema:
$ref: '#/components/schemas/RFC7231.HTTP-date'
headers:
Content-Length:
description: Size in bytes of the response body.
schema:
type: integer
example: 80
Content-Length-0:
description: Size in bytes of the response body. Always set to 0.
schema:
type: integer
minimum: 0
maximum: 0
default: 0
example: 0
Content-Type-GZip:
description: Content-Type header set as "application/gzip".
schema:
type: string
example: application/gzip
Content-Type-Pkix-Crl:
description: Content-Type header set as "application/pkix-crl".
schema:
type: string
example: application/pkix-crl