-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathoauth2.raml
891 lines (820 loc) · 43.6 KB
/
oauth2.raml
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
#%RAML 0.8
title: YaasApiOAuth2V1
version: v1
mediaType: application/json
baseUri: https://api.eu.yaas.io/hybris/oauth2/v1
securitySchemes:
- !include https://api.yaas.io/patterns/v1/security-schema-basic.yaml
schemas:
-
userInfoClaims: |
{
"$schema" : "http://schemas-schema.org/draft-04/schema",
"type" : "object",
"title" : "UserInfo Claims",
"properties" : {
"sub" : {
"description" : "Subject - Identifier for the End-User at the Issuer",
"type" : "string",
"required" : true
},
"tenant" : {
"description" : "Tenant for which End-User is authenticated (Private Claim)",
"type" : "string",
"required" : false
}
}
}
-
oauth2Error: |
{
"$schema" : "http://schemas-schema.org/draft-04/schema",
"type" : "object",
"title" : "UserInfo Claims",
"properties" : {
"error" : {
"description" : "Error",
"type" : "string",
"required" : true
},
"errorDescription" : {
"description" : "Error description",
"type" : "string",
"required" : false
}
}
}
-
clientCredentialsResponse: |
{
"$schema" : "http://schemas-schema.org/draft-04/schema",
"type" : "object",
"title" : "UserInfo Claims",
"properties" : {
"access_token" : {
"description" : "",
"type" : "string",
"required" : true
},
"expires_in" : {
"description" : "",
"type" : "number",
"required" : true
},
"token_type" : {
"description" : "",
"type" : "string",
"required" : true
},
"traits" : {
"description" : "",
"type" : "string",
"required" : false
}
}
}
traits:
- oauth2:
usage: Apply this trait to support OAuth 2.0 authentication.
description: |
Supports OAuth 2.0 for authenticating all API requests.
headers:
Authorization:
type: string
description: |
Used to send a valid OAuth2 access token.
example: Bearer access_token
required: true
responses:
401:
description: |
Given request is unauthorized. Bad or expired token. Reauthenticate
the user. Any details will be provided within the response payload.
body:
application/json:
example: |
{
"status":401,
"message":"Authorization: Unauthorized. Bearer TOKEN is invalid",
"type":"insufficient_credentials",
"moreInfo":"https://api.beta.yaas.io/patterns/errortypes.html"
}
schema: |
{
"$schema":"http://json-schema.org/draft-04/schema#",
"title":"error",
"description":"Schema for API specified errors.",
"type":"object",
"properties":
{
"status":
{
"type":"integer",
"description":"original HTTP error code, should be consistent with the response HTTP code",
"minimum":100,
"maximum":599
},
"type":
{
"type":"string",
"description":"classification of the error type, lower case with underscore eg validation_failure",
"pattern":"[a-z]+[a-z_]*[a-z]+"
},
"message":
{
"type":"string",
"description":"descriptive error message for debugging"
},
"moreInfo":
{
"type":"string",
"format":"uri",
"description":"link to documentation to investigate further and finding support"
},
"details":
{
"type":"array",
"description":"list of problems causing this error",
"items":
{
"$schema":"http://json-schema.org/draft-04/schema#",
"title":"errorDetail",
"description":"schema for specific error cause",
"type":"object",
"properties":
{
"field":
{
"type":"string",
"description":"a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type":
{
"type":"string",
"description":"classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern":"[a-z]+[a-z_]*[a-z]+"
},
"message":
{
"type":"string",
"description":"descriptive error detail message for debugging"
},
"moreInfo":
{
"type":"string",
"format":"uri",
"description":"link to documentation to investigate further and finding support for error detail"
}
},
"required":["type"]
}
}
},
"required":["status" , "type" ]
}
403:
description: |
Evaluated request scopes in access token are not sufficient and do not match required scopes.
body:
application/json:
example: |
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
schema: |
{
"$schema":"http://json-schema.org/draft-04/schema#",
"title":"error",
"description":"Schema for API specified errors.",
"type":"object",
"properties":
{
"status":
{
"type":"integer",
"description":"original HTTP error code, should be consistent with the response HTTP code",
"minimum":100,
"maximum":599
},
"type":
{
"type":"string",
"description":"classification of the error type, lower case with underscore eg validation_failure",
"pattern":"[a-z]+[a-z_]*[a-z]+"
},
"message":
{
"type":"string",
"description":"descriptive error message for debugging"
},
"moreInfo":
{
"type":"string",
"format":"uri",
"description":"link to documentation to investigate further and finding support"
},
"details":
{
"type":"array",
"description":"list of problems causing this error",
"items":
{
"$schema":"http://json-schema.org/draft-04/schema#",
"title":"errorDetail",
"description":"schema for specific error cause",
"type":"object",
"properties":
{
"field":
{
"type":"string",
"description":"a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type":
{
"type":"string",
"description":"classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern":"[a-z]+[a-z_]*[a-z]+"
},
"message":
{
"type":"string",
"description":"descriptive error detail message for debugging"
},
"moreInfo":
{
"type":"string",
"format":"uri",
"description":"link to documentation to investigate further and finding support for error detail"
}
},
"required":["type"]
}
}
},
"required":["status" , "type" ]
}
/revoke:
description: |
Revokes given access token.
post:
description: |
Revokes given access token.
headers:
Authorization:
type: string
description: |
Provides the Bearer access token to revoke.
example: Bearer 9221efd2-ce35-4a3e-ae04-7af778cfc4ac
required: true
responses:
200:
description: Token has been revoked.
401:
description: |
Response is returned if:
<ul>
<li>Auhtorization header was not sent, OR</li>
<li>Header was sent but with an empty value or without the access token value, OR</li>
<li>Wrong authorization method was used.</li>
</ul>
Valid request must contain Authorization header in the format: Bearer ACCESS_TOKEN.
/authorize:
description: |
Use the OAuth2 Authorization Endpoint to authenticate and obtain an authorization grant.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.1">OAuth 2.0 specification (rfc6749#section-3.1)</a> and <a target="blank" title="Getting Started" href="/gettingstarted/index.html">Getting Started</a> tutorial.
get:
description: |
Starts the authorization procedure with the parameters specified in the URL query.
queryParameters:
response_type:
type: string
description: |
This value can be "token" or "id_token token" (currently only the Implicit Grant flow, as described in <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.1">rfc6749#section-4.2.1</a>, is supported).<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.1.1">OAuth 2.0 specification (rfc6749#section-3.1.1)</a>.
example: token
required: true
client_id:
type: string
description: |
This is the client identifier, available in the Client Authorization section in the Builder.
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-2.2">OAuth 2.0 specification (rfc6749#section-2.2)</a>.
required: true
redirect_uri:
type: string
description: |
This URL is used as a callback after a successful authentication and authorization grant to redirect the access token. This is:<br/>
- **OPTIONAL** if only one redirect URI is registered for your application.<br/>
- **REQUIRED** if multiple redirect URIs are registered for your application (must match at least one of these URIs).<br/>
For security reasons, TLS should be used for redirect URIs.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 specification (rfc6749#section-3.1.2)</a>.
required: false
scope:
type: string
description: |
This lists the requested scope of the access.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.3">OAuth 2.0 specification (rfc6749#section-3.3)</a>.<br/>
The predefined scopes are:<br/>
- **hybris.tenant={tenantName}** - This enables you to specify the tenant for which an access token should be issued.<br/>
If neither this scope nor hybris.no\_tenant is specified, and the user account is associated with multiple tenants, the authorization server displays an additional page which enables the user to select the appropriate tenant.<br/>
If both this scope and hybris.no\_tenant are specified, the server responds with a redirection to the redirect\_uri or registered redirect URL with the 'error' parameter set to 'invalid\_scope' and 'error\_description' with the error details.<br/>
- **hybris.no\_tenant** - This enables you to omit the tenant chooser.<br/>
If neither this scope nor hybris.tenant is specified, and the user account is associated with multiple tenants, the authorization server displays an additional page which enables the user to select the appropriate tenant.<br/>
If both this scope and hybris.tenant are specified, the server responds with a redirection to the redirect\_uri or registered redirect URL with the 'error' parameter set to 'invalid\_scope' and 'error\_description' with the error details.<br/>
- **hybris.org={organizationID}** - This enables yout to specify the organization for which an access token should be issued.<br/>
Using both this scope and hybris.tenant or hybris.no_tenant is not allowed.
example: "hybris.tenant%3Dfa4dvht53fgb%20hybris.manage%20hybris.view"
required: false
state:
type: string
description: |
RECOMMENDED. This is an opaque value used by the client to maintain the state between the request and the redirect.<br/>
This value is included when redirecting the user agent back to the client.<br/>
The parameter should be used to prevent cross-site request forgery as described in the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-10.12">OAuth 2.0 specification (rfc6749#section-10.12)</a>.
example: |
security_token%3D9F2a3290Daa126P%26custom_state%3Dhttps://hybris.com/index.html
required: false
id_token_hint:
type: string
description: |
This value is used in subsequent requests for the access token (the actual ID token that was received in the previous request).
required: false
nonce:
type: string
description: |
This value is used to prevent replay attacks when using id_token. It must have sufficient entropy.
required: false
display:
type: string
description: |
This value specifies how the authorization server displays the authentication and tenant chooser pages to the end user. <br/>The supported values are:<br/>
- `popup` for transparent background<br/>
- `page` for default display
example: page
required: false
hybris-session-id:
type: string
description: |
This is the session identifier. It is generated if not passed.
required: false
responses:
200:
description: |
The authentication page or the tenant chooser page for multi-tenant clients.<br/>
302:
description: |
The redirection to the redirect_uri or the registered redirect URL.
headers:
location:
description: |
The redirection URL equals the redirect\_uri if it was specified in the request. Otherwise, it equals the registered redirect URL. If multiple redirect URLs are registered, the redirect_uri parameter is required.<br/>
It contains the following parameters in the URL Fragment Component:
<ul>
<li>If the authentication and the authorization grant succeed:
<ul>
<li>**access_token** - This is the access token issued by the authorization server.</li>
<li>**token_type** - This is the type of the token issued. The value is "bearer".<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-7.1">OAuth 2.0 specification (rfc6749#section-7.1)</a>.</li>
<li>**expires_in** - This is the lifetime in seconds of the access token.</li>
<li>**scope** - This lists the effective scope of the access token. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.3">OAuth 2.0 specification (rfc6749#section-3.3)</a>.</li>
<li>**state** - This is the exact value received from the client if it was specified in the request "state" parameter.</li>
</ul>
</li>
<li>If the resource owner denies the access request, or if the request fails for reasons other than a missing or invalid redirection URI:
<ul>
<li>**error** - This is a single ASCII error code from the following:
<ul>
<li>**invalid_request** - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.</li>
<li>**unauthorized_client** - The client is not authorized to request an access token using this method.</li>
<li>**access_denied** - The resource owner or authorization server denied the request.</li>
<li>**unsupported_response_type** - The authorization server does not support obtaining an access token using this method.</li>
<li>**invalid_scope** - The requested scope is invalid, unknown, or malformed.</li>
<li>**server_error** - The authorization server encountered an unexpected condition that prevented it from completing the request.</li>
<li>**temporarily_unavailable** - The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.</li>
</ul>
</li>
<li>**error_description** - This is a human-readable ASCII text line providing additional information that is used to assist the client developer in understanding the returned error.</li>
<li>**error_uri** - This is a URI identifying a human-readable webpage with information about the error that is used to provide the client developer with additional information about the error.</li>
<li>**state** - This is the exact value received from the client if it was specified in the request "state" parameter.</li>
</ul>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.2.1">OAuth 2.0 specification (rfc6749#section-4.2.2.1)</a>.</li>
</li>
</ul>
required: true
type: string
displayName: location
400:
description: |
Bad request is returned if the parameter:
<ul>
<li>client_id is missing (the redirect_uri cannot be verified and redirect URL is not found)</li>
<li>client_id has an invalid value (the redirect_uri cannot be verified and redirect URL is not found)</li>
<li>client_id is included in the request more than once</li>
<li>redirect_uri is missing and is required because multiple redirect URLs are registered</li>
<li>redirect_uri has invalid value</li>
<li>redirect_uri is included in the request more than once</li>
</ul>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.2.1">OAuth 2.0 specification (rfc6749#section-4.2.2.1)</a>.</li>
post:
description: |
This starts the authorization procedure with the parameters specified in the request body (form parameters).
body:
application/x-www-form-urlencoded:
formParameters:
response_type:
description: |
This value can be "token" or "id_token token" (currently only Implicit Grant flow, as described in <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.1">rfc6749#section-4.2.1</a>, is supported).<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.1.1">OAuth 2.0 specification (rfc6749#section-3.1.1)</a>.
example: token
required: true
type: string
displayName: response_type
client_id:
description: |
This is the client identifier, available in the Client Authorization section in the Builder. For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-2.2">OAuth 2.0 specification (rfc6749#section-2.2)</a>.
required: true
type: string
displayName: client_id
redirect_uri:
description: |
This URL is used as a callback after a successful authentication and authorization grant to redirect the access token. This is:<br/>
- **OPTIONAL** if only one redirect URI is registered for your application.<br/>
- **REQUIRED** if multiple redirect URIs are registered for your application (must match at least one of these URIs).<br/>
For security reasons, TLS should be used for redirect URIs.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 specification (rfc6749#section-3.1.2)</a>.
required: false
type: string
displayName: redirect_uri
scope:
description: |
This lists the requested scope of the access.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.3">OAuth 2.0 specification (rfc6749#section-3.3)</a>.<br/>
The predefined scopes:<br/>
- **hybris.tenant={tenantName}** - This enables you to specify the tenant for which an access token should be issued.<br/>
If neither this scope nor hybris.no\_tenant is specified and the user account is associated with multiple tenants, the authorization server displays an additional page which enables the user to select the appropriate tenant.<br/>
If both this scope and hybris.no\_tenant are specified, the server responds with a redirection to the redirect\_uri or registered redirect URL with the 'error' parameter set to 'invalid\_scope' and 'error\_description' with the error details.<br/>
- **hybris.no\_tenant** - Enables you to omit the tenant chooser.<br/>
If neither this scope nor hybris.tenant is specified and the user account is associated with multiple tenants, the authorization server displays an additional page which enables the user to select the appropriate tenant.<br/>
If both this scope and hybris.tenant are specified, the server responds with a redirection to the redirect\_uri or registered redirect URL with the 'error' parameter set to 'invalid\_scope' and 'error\_description' with the error details.<br/>
- **hybris.org={organizationID}** - This enables you to specify the organization for which an access token should be issued.<br/>
Using both this scope and hybris.tenant or hybris.no_tenant is not allowed.
example: hybris.tenant=fa4dvht53fgb hybris.manage hybris.view
required: false
type: string
displayName: scope
state:
description: |
RECOMMENDED. This is an opaque value used by the client to maintain the state between the request and the redirect.<br/>
This value is included when redirecting the user agent back to the client.<br/>
The parameter should be used for preventing cross-site request forgery as described in the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-10.12">OAuth 2.0 specification (rfc6749#section-10.12)</a>.
example: |
security_token=9F2a3290Daa126P&custom_state=https://hybris.com/index.html
required: false
type: string
displayName: state
id_token_hint:
description: |
This value is used in the subsequent requests for the access token (the actual ID token that was received in the previous request).
required: false
type: string
displayName: id_token_hint
nonce:
description: |
This value is used to prevent replay attacks when using the id_token. It must have sufficient entropy.
required: false
type: string
displayName: nonce
display:
description: |
This value specifies how the authorization server displays the authentication and tenant chooser pages to the end user. <br/>The supported values are:<br/>
- `popup` for transparent background<br/>
- `page` for default display
example: page
required: false
type: string
displayName: display
hybris-session-id:
description: |
This is the session identifier. It is generated if not passed.
required: false
type: string
displayName: hybris-session-id
responses:
200:
description: |
The authentication page or the tenant chooser page for multi-tenant clients.
302:
description: |
The redirection to the redirect_uri or the registered redirect URL.
headers:
location:
description: |
The redirection URL equals the redirect\_uri if it was specified in the request. Otherwise, it equals the registered redirect URL (if multiple redirect URLs are registered, the redirect_uri is required).<br/>
It contains the following parameters in the URL Fragment Component:
<ul>
<li>If the authentication and the authorization grant succeed:
<ul>
<li>**access_token** - This is the access token issued by the authorization server.</li>
<li>**token_type** - This is the type of token issued. The value is "bearer".<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-7.1">OAuth 2.0 specification (rfc6749#section-7.1)</a>.</li>
<li>**expires_in** - This is the lifetime in seconds of the access token.</li>
<li>**scope** - This lists the effective scope of the access token. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.3">OAuth 2.0 specification (rfc6749#section-3.3)</a>.</li>
<li>**state** - This is the exact value received from the client if it was specified in the request "state" parameter.</li>
</ul>
</li>
<li>If the resource owner denies the access request, or if the request fails for reasons other than a missing or invalid redirection URI:
<ul>
<li>**error** - This is a single ASCII error code from the following:
<ul>
<li>**invalid_request** - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.</li>
<li>**unauthorized_client** - The client is not authorized to request an access token using this method.</li>
<li>**access_denied** - The resource owner or authorization server denied the request.</li>
<li>**unsupported_response_type** - The authorization server does not support obtaining an access token using this method.</li>
<li>**invalid_scope** - The requested scope is invalid, unknown, or malformed.</li>
<li>**server_error** - The authorization server encountered an unexpected condition that prevented it from completing the request.</li>
<li>**temporarily_unavailable** - The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.</li>
</ul>
</li>
<li>**error_description** - This is a human-readable ASCII text line providing additional information that is used to assist the client developer in understanding the error that was returned.</li>
<li>**error_uri** - This is a URI identifying a human-readable webpage with information about the error that is used to provide the client developer with additional information about the error.</li>
<li>**state** - This is the exact value received from the client if it was specified in the request "state" parameter.</li>
</ul>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.2.1">OAuth 2.0 specification (rfc6749#section-4.2.2.1)</a>.</li>
</li>
</ul>
required: true
type: string
displayName: location
400:
description: |
Bad request is returned if the parameter:
<ul>
<li>client_id is missing (the redirect_uri cannot be verified and redirect URL is not found)</li>
<li>client_id has an invalid value (the redirect_uri cannot be verified and redirect URL is not found)</li>
<li>client_id is included in the request more than once</li>
<li>redirect_uri is missing and it is required because multiple redirect URLs are registered</li>
<li>redirect_uri has an invalid value</li>
<li>redirect_uri is included in request more than once</li>
</ul>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-4.2.2.1">OAuth 2.0 specification (rfc6749#section-4.2.2.1)</a>.</li>
/token:
description: |
Use this endpoint to obtain an access token for a client.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.2">OAuth 2.0 specification (rfc6749#section-3.2)</a> and <a target="blank" title="Getting Started" href="https://devportal.yaas.io/gettingstarted/index.html">Getting Started</a> tutorial.
post:
description: |
Use only ONE of the authorization types:
<ul>
<li>[RECOMMENDED] `Authorization` header, OR</li>
<li>`client_id` and `client_secret` body parameters. Remove the content of the prefilled <strong>Authorization</strong> Basic example when you use this authorization type.</li>
</ul>
Examples:
- Client Credentials grant type
```sh
curl -X POST 'https://api.beta.yaas.io/hybris/oauth2/v1/token' \
-d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=scope1' \
-H 'content-type: application/x-www-form-urlencoded'
```
- Resource Owner Password Credentials grant type
```sh
curl -X POST 'https://api.beta.yaas.io/hybris/oauth2/v1/token' \
-d 'grant_type=password&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&username=USERNAME&password=USER_PASSWORD&scope=scope1' \
-H 'content-type: application/x-www-form-urlencoded'
```
headers:
Authorization:
type: string
description: |
Provides the basic authorization:<br />
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-2.3.1">OAuth 2.0 specification (rfc6749#section-2.3.1)</a>.
example: Basic REPLACE_WITH_BASE64_ENCODED_CLIENT_CREDENTIALS_OR_REMOVE
required: false
body:
application/x-www-form-urlencoded:
formParameters:
grant_type:
description: |
The grant type of the request. The value MUST be set to `client_credentials` or `password`.
example: client_credentials
required: true
type: string
displayName: grant_type
scope:
description: |
Lists the requested scope of the access.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-3.3">OAuth 2.0 specification (rfc6749#section-3.3)</a>.<br/>
The predefined scope is:<br/>
- **hybris.tenant={tenantName}** - This enables you to specify the tenant for which an access token should be issued.<br/>
It may be used for multi-tenant clients: Services or Builder modules. It is set to the ID of the team that created the client if not passed. This must be set to the ID of the project that should be used in subsequent requests with the access token.
example: hybris.tenant=fa4dvht53fgb hybris.manage hybris.view
required: false
type: string
displayName: scope
client_id:
description: |
Client identifier. This is required for `client_credentials` grant type when the **Authorization** header is omitted.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-2.2">OAuth 2.0 specification (rfc6749#section-2.2)</a>.
required: false
type: string
displayName: client_id
client_secret:
description: |
Client secret. This is required for `client_credentials` grant type when the **Authorization** header is omitted.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-2.3.1">OAuth 2.0 specification (rfc6749#section-2.3.1)</a>.
required: false
type: string
displayName: client_secret
username:
description: |
Resource owner username. This is required for the `password` grant type.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="https://tools.ietf.org/html/rfc6749#section-4.3.2">OAuth 2.0 specification (rfc6749#section-4.3.2)</a>.
required: false
type: string
displayName: username
password:
description: |
Resource owner password. This is required for the `password` grant type.<br/>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="https://tools.ietf.org/html/rfc6749#section-4.3.2">OAuth 2.0 specification (rfc6749#section-4.3.2)</a>.
required: false
type: string
displayName: password
hybris-session-id:
description: |
Session identifier. It is generated if not passed.
required: false
type: string
displayName: hybris-session-id
hybris_id_provider:
description: |
ID provider. Use it only with `password` grant type.
required: false
type: string
displayName: hybris_id_provider
responses:
200:
body:
application/json:
schema: clientCredentialsResponse
example: |
{
"access_token" : "2YotnFZFEjr1zCsicMWpAA",
"expires_in" : 3600,
"token_type": "Bearer",
"scope": "hybris.MANAGE hybris.READ"
}
400:
description: |
The bad request error is returned if:
<ul>
<li>The Authorization header is missing</li>
<li>client_id is missing or has an invalid value</li>
<li>grant_type is missing or has an invalid value</li>
<li>hybris-tenant is missing</li>
</ul>
For more information, see the <a target="blank" title="OAuth2 RFC 6749" href="http://tools.ietf.org/html/rfc6749#section-5.2">OAuth 2.0 specification (rfc6749#section-5.2)</a>.</li>
body:
application/json:
schema: oauth2Error
example: |
{
"error": "invalid_grant",
"errorDescription": "client_code is not supported grant type."
}
/userinfo:
description: |
Use the OpenID UserInfo endpoint to retrieve claims about the authenticated end user.<br/>
For more information, see the <a target="blank" title="UserInfo Endpoint - OpenId Connect Core 1.0 Specification" href="http://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.3">UserInfo Endpoint - OpenId Connect Core 1.0 Specification (section 5.3)</a>.
get:
description: |
Returns claims about the authenticated end user.
headers:
Authorization:
type: string
description: |
Provides the `Bearer` access token for which the user information is returned.
example: Bearer 9221efd2-ce35-4a3e-ae04-7af778cfc4ac
required: true
responses:
200:
description: Claims about the authenticated end user.
body:
application/json:
schema: userInfoClaims
example: |
{
"sub": "[email protected]",
"tenant": "sampleTenant"
}
post:
description: |
Returns claims about the authenticated end user.
headers:
Authorization:
type: string
description: |
Provides the `Bearer` access token for which the user information is returned.
example: Bearer 9221efd2-ce35-4a3e-ae04-7af778cfc4ac
required: true
responses:
200:
description: Claims about the authenticated end user.
body:
application/json:
schema: userInfoClaims
example: |
{
"sub": "[email protected]",
"tenant": "sampleTenant"
}
/tokeninfo:
description: |
Use this endpoint to obtain information about your token
get:
description: |
When the query parameters <strong>access_token</strong> is provided, this endpoint returns tenant, scopes, allowedServices, etc. associated with the access token.
queryParameters:
access_token:
type: string
description: Token for diagnostics
example: 021-9573cc7b-e623-4b81-8cb1-480edd9709e0
required: true
details:
type: boolean
description: |
When this is set to <strong>true</strong>, the response will contain additional information (e.g allowedServices field).
example: false
required: false
responses:
200:
body:
application/json:
schema: |
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "tokeninfo",
"properties": {
"tenant": {
"description": "Tenant for which token was issued.",
"type": "string"
},
"scopes": {
"description": "This lists the scopes that the access token includes.",
"type": "array"
},
"user": {
"description": "User for which token was issued.",
"type": "string"
},
"allowedServices": {
"description": "This lists the services you can call with the access token.",
"type": "array"
},
"clientId" : {
"description": "clientId for which token was issued.",
"type": "string"
}
}
}
example: |
{
"scopes": [
"hybris.coupon_manage",
"hybris.tenant=some_tenant"
],
"tenant": "some_tenant",
"clientId": "gnn854bC9iSwDGH64BM5TorHcVesdsJ4Cs",
"allowedServices": [
{
"name": "coupon",
"proxyUrl": [
"https://api.beta.yaas.io/hybris/coupon/v1"
],
"serviceScopes": [
"hybris.coupon_manage",
"hybris.coupon_redeem",
"hybris.coupon_redeem_on_behalf"
]
}
]
}
400:
description: |
The bad request error is returned if:
<ul>
<li>access_token query parameters is missing</li>
<li>access_token is invalid or expired</li>
</ul>
body:
application/json:
schema: oauth2Error
example: |
{
"error": "invalid_query_parameter",
"error_description": "access_token is invalid",
"error_uri": "https://api.beta.yaas.io/patterns/errortypes.html"
}