-
Notifications
You must be signed in to change notification settings - Fork 0
/
hm-oauth-rest-v1.yml
373 lines (357 loc) · 15.3 KB
/
hm-oauth-rest-v1.yml
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
openapi: 3.0.3
info:
title: OAuth2 API
description: >-
The OAuth2 API provides you an interface to create access tokens which could be used for :
* Vehicle resource : Access and refresh access tokens, which are issued on a VIN-basis to be used with any of the pull-based data APIs.
* Application resource: Access tokens, which are used to access an application resource. e.g Clearance APIs, Eligibility API and Vehicle data for fleets.
The OAuth2 server addresses are listed in your application view within the platform console.
Sandbox server: `https://sandbox.api.high-mobility.com`
Production server: `https://api.high-mobility.com`
version: '1.0'
servers:
- url: https://api.high-mobility.com
- url: https://sandbox.api.high-mobility.com
tags:
- name: OAuth2
description: Operations about OAuth2
paths:
/v1/access_tokens:
post:
tags:
- OAuth2
summary: 'Creates and renews AccessTokens'
description: This API implements rfc7009, rfc7636 and rfc6749
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokensReponse'
examples:
"ConsentFlow:web: Get access token":
value:
access_token: 81bcb5ee-3aa1-4fc6-bc54-79019af30a45
expires_in: 3600
refresh_token: b39c3380-a8cf-48fe-ad80-d70279a4a5d6
scope: diagnostics.get.mileage doors.get.locks windows.get.positions
status: approved
token_type: bearer
"ConsentFlow:web: Refresh access token":
value:
access_token: 81bcb5ee-3aa1-4fc6-bc54-79019af30a45
expires_in: 3600
refresh_token: b39c3380-a8cf-48fe-ad80-d70279a4a5d6
scope: diagnostics.get.mileage doors.get.locks windows.get.positions
status: approved
token_type: bearer
"ConsentFlow:in-app: Get access token":
value:
access_token: 81bcb5ee-3aa1-4fc6-bc54-79019af30a45
expires_in: 3600
refresh_token: b39c3380-a8cf-48fe-ad80-d70279a4a5d6
scope: diagnostics.get.mileage doors.get.locks windows.get.positions
status: approved
token_type: bearer
"ConsentFlow:in-app: Refresh access token":
value:
access_token: 81bcb5ee-3aa1-4fc6-bc54-79019af30a45
expires_in: 3600
refresh_token: b39c3380-a8cf-48fe-ad80-d70279a4a5d6
scope: diagnostics.get.mileage doors.get.locks windows.get.positions
status: approved
token_type: bearer
"ApplicationApiKey: Get access token using client_credentials":
value:
access_token: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTc5NjU5NTgsImlhdCI6MTY5Nzk2NTY1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo0MDAwL3YxL2F1dGhfdG9rZW5zIiwic2NvcGUiOiJmbGVldDpjbGVhcmFuY2UgdmVoaWNsZTplbGlnaWJpbGl0eS1jaGVjayB2ZWhpY2xlOmRhdGEiLCJzdWIiOiIzNTZmZjA3OS01ZGMzLTRjZmEtOWY3Yy05MTNhOTdlYzZjMjQiLCJ2ZXIiOjF9.pfbRQ4hDBwyPAAe4qdfFnfLQ9bceDIzxY6sVjDy9LD1v8uAueQ4qIIbSNQc2rm9gWHilwXS9Z-BeSN5GhnMrwA
expires_in: 300
scope: fleet:clearance vehicle:eligibility-check vehicle:data
token_type: bearer
"ApplicationApiKey: Get access token using client_credentials with client_assertion":
value:
access_token: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTc5NjU5NTgsImlhdCI6MTY5Nzk2NTY1OCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo0MDAwL3YxL2F1dGhfdG9rZW5zIiwic2NvcGUiOiJmbGVldDpjbGVhcmFuY2UgdmVoaWNsZTplbGlnaWJpbGl0eS1jaGVjayB2ZWhpY2xlOmRhdGEiLCJzdWIiOiIzNTZmZjA3OS01ZGMzLTRjZmEtOWY3Yy05MTNhOTdlYzZjMjQiLCJ2ZXIiOjF9.pfbRQ4hDBwyPAAe4qdfFnfLQ9bceDIzxY6sVjDy9LD1v8uAueQ4qIIbSNQc2rm9gWHilwXS9Z-BeSN5GhnMrwA
expires_in: 300
scope: fleet:clearance vehicle:eligibility-check vehicle:data
token_type: bearer
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokensError'
examples:
"Missing required params":
value:
error: invalid_request
error_description: client_id can't be blank, client_secret can't be blank, grant_type can't be blank
"Invalid client_secret":
value:
error: invalid_request
error_description: client_secret is invalid
"ConsentFlow:web: invalid code":
value:
error: invalid_request
error_description: code is invalid
"ApplicationApiKey: expired key":
value:
error: invalid_request
error_description: client_assertion is signed with an expired key
description: Error
'500':
description: Server Errors
requestBody:
description: OAuth request payload
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokensRequest'
examples:
"ConsentFlow:web: Get access token":
description: After the user has finished the consent flow, the oauth client needs to exchange authorization `code` with `access_token`
value:
grant_type: authorization_code
code: "7672e33d-fdc0-47f0-bd17-6c1e727271f8"
redirect_uri: "http://localhost/mycallback"
client_id: "09ce38c6-5cd7-47b0-b271-235414e938c6"
client_secret: "rzeVs5nnx5OCMQejjfQTjLE8Jb2ReFSU"
"ConsentFlow:web: Refresh access token":
description: When an access token is expired, the oauth client needs to refresh access token and obtain a new `access_token`
value:
grant_type: refresh
client_id: "09ce38c6-5cd7-47b0-b271-235414e938c6"
client_secret: "rzeVs5nnx5OCMQejjfQTjLE8Jb2ReFSU"
refresh_token: "6f3ab59b-9fb5-42ba-8e5b-574757fbffc8"
"ConsentFlow:in-app: Get access token":
description: Same as `ConsentFlow:web` examples but `client_secret` is not needed. Also `redirect_url` must be match with oauth client's "URL-scheme"
value:
grant_type: authorization_code
code: "7672e33d-fdc0-47f0-bd17-6c1e727271f8"
redirect_uri: "com.hm.1533642514-lsgujv3umopt"
client_id: "09ce38c6-5cd7-47b0-b271-235414e938c6"
code_verifier: "the-random-generated-verifier"
"ConsentFlow:in-app: Refresh access token":
description: Same as `ConsentFlow:web` examples but `client_secret` is not needed.
value:
grant_type: refresh
client_id: "09ce38c6-5cd7-47b0-b271-235414e938c6"
refresh_token: "6f3ab59b-9fb5-42ba-8e5b-574757fbffc8"
"ApplicationApiKey: Get access token using client_credentials":
description: The client credentials grant is used when applications request an access token to access their own resources, not on behalf of a user
value:
grant_type: client_credentials
client_id: "09ce38c6-5cd7-47b0-b271-235414e938c6"
client_secret: "rzeVs5nnx5OCMQejjfQTjLE8Jb2ReFSU"
"ApplicationApiKey: Get access token using client_credentials with client_assertion":
description: The client credentials grant is used when applications request an access token to access their own resources, not on behalf of a user. In this method a private key is used to create JWT as `client_assertion`
value:
grant_type: client_credentials
client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_id: "40568550-5ace-4d72-b45b-f46679b620aa"
client_assertion: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjQwMDAvdjEiLCJpc3MiOiI1ZTNjYzM0OS0xYzZmLTQ5NzUtYWVhYS05ZDMxOTA4NjE5MGIiLCJ2ZXIiOjIsImlhdCI6MTY5ODIzMjUwNywianRpIjoic2VqTG8xMnRENzNZSFE9PSJ9.HTZp4E5CJvGgk-XnWrKizQ6itqHmARXuE4iBYYztJ-6EGNTMAzkdSUMZB7aWSjfcXQyS9-08xp3yBrmf-9QWAA
delete:
tags:
- OAuth2
summary: 'Revokes AccessTokens'
description: This API implements rfc7009
responses:
'200':
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokensError'
description: Error
'503':
description: Server Errors
requestBody:
description: OAuth delete payload
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokensRevoke'
/v1/vehicleinfo:
get:
tags:
- OAuth2
parameters:
- in: header
name: Authorization
required: true
schema:
type: string
format: uuid
description: Bearer token
summary: 'Checks AccessTokens vehicleinfo'
description: Returns vehicleinfo associated with access token
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleInfoResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleInfoError'
description: Error
'500':
description: Server Errors
components:
schemas:
AccessTokensReponse:
type: object
title: AccessTokensReponse
required:
- expires_in
- access_token
- token_type
properties:
validity_start_date:
type: string
description: 'Date and Time in ISO8601 format example: ''2018-11-06T10:20:37.094533Z'''
validity_end_date:
type: string
description: 'Date and Time in ISO8601 format example: ''2018-11-06T10:20:37.094533Z'''
token_type:
type: string
description: Token type
scope:
type: string
description: List of scopes
refresh_token:
type: string
description: Refresh token should be used after the access token is expired to fetch a new access token
expires_in:
type: integer
description: Expiration time in seconds
authorization_id:
type: string
description: Authorization Id could be used later on in authorization_changed Webhook
access_token:
type: string
description: Access token
status:
type: string
description: In BMW and MINI case, the status is pending until the car owner grants access in BMW ConnectedDrive Portal
enum:
- pending
- approved
example:
validity_start_date: '2018-11-01T00:01:02.094533Z'
validity_end_date: '2020-12-31T10:20:37.094533Z'
token_type: bearer
scope: diagnostics.mileage door_locks.locks windows.windows_positions
refresh_token: 7f7a9be0-04c9-4202-a59f-35d55079b6ba
expires_in: 600
access_token: a50e89e5-093c-4727-8101-4c6e81addabe
status: pending
description: Access Tokens
AccessTokensRequest:
type: object
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
- client_credentials
description: Grant Type.
code:
type: string
description: Authorization code that the client previously received from the authorization server. Required when grant_type is authorization_code.
redirect_uri:
type: string
description: The redirect URI in the token request must be an exact match of the redirect URI that was used when generating the authorization code. Required for when grant_type is authorization_code.
refresh_token:
type: string
description: Refresh token that the client previously received from the authorization server. Required when grant_type is refresh_token.
client_id:
type: string
description: Client ID used for authentication.
client_secret:
type: string
description: Client Secret used for authentication, only used in Server-Side Apps
code_verifier:
type: string
description: Code verifier(PKCE), only used in Mobile and Native Apps
client_assertion:
description: Only used with the combination of client_credentials grant_type and client_assertion_type
type: string
client_assertion_type:
description: Only used with the combination of client_credentials grant_type and client_assertion
type: string
enum:
- urn:ietf:params:oauth:client-assertion-type:jwt-bearer
required:
- grant_type
- client_id
AccessTokensRevoke:
type: object
properties:
token:
type: string
description: Access Token or Refresh Token that will be used in the revocation.
client_id:
type: string
description: Client ID used for authentication.
client_secret:
type: string
description: Client Secret used for authentication, only used in Server-Side Apps
token_type_hint:
type: string
enum:
- refresh_token
- access_token
description: Token hint used to identify which type of token is inside the token property.
required:
- client_id
- client_secret
- token
AccessTokensError:
type: object
title: AccessTokensError
required:
- error
properties:
error_description:
type: string
description: Error description
error:
type: string
description: Error code
description: Error details
VehicleInfoResponse:
type: object
title: VehicleInfoResponse
required:
- vin
- sub
properties:
vin:
type: string
description: 'VIN associated with the access token'
sub:
type: string
description: 'sub associated with the access token'
example:
vin: 'VIN00000000000001'
sub: '00000000-0000-0000-0000-000000000000'
description: Vehicle Info
VehicleInfoError:
type: object
title: VehicleInfoError
required:
- error
properties:
error_description:
type: string
description: Error description
error:
type: string
description: Error code
description: Error details