-
Notifications
You must be signed in to change notification settings - Fork 19
/
oauth-minimal.yaml
4687 lines (4595 loc) · 211 KB
/
oauth-minimal.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
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
openapi: 3.0.3
info:
title: Okta OpenID Connect & OAuth 2.0
version: 2024.08.3
description: OAuth 2.0 Protocol APIs
termsOfService: https://developer.okta.com/terms/
contact:
name: Okta Developer Team
url: https://developer.okta.com/
email: devex-public@okta.com
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
x-logo:
url: logo.svg
backgroundColor: transparent
altText: Okta Developer
servers:
- url: https://{yourOktaDomain}
variables:
yourOktaDomain:
default: subdomain.okta.com
description: The domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains.
tags:
- name: Client
x-displayName: Dynamic Client Registration
description: |-
The Dynamic Client Registration API provides operations to register and manage client Applications for use with Okta's OAuth 2.0 and OpenID Connect endpoints. This API largely follows the contract defined in [RFC7591: OAuth 2.0 Dynamic Client Registration Protocol](https://tools.ietf.org/html/rfc7591) and [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html).
> **Note:** Clients managed through this API are modeled as Applications in Okta and appear in the Applications section of the Admin Console. Changes made through the API appear in the UI and vice versa. Tokens issued by these clients follow the rules for access tokens and ID tokens.
- name: CustomAS
x-displayName: Custom Authorization Servers
description: |-
Use a custom authorization server to create and apply authorization policies to secure your APIs. An access token that's minted by a custom authorization server is consumed by your APIs.
> **Note:** Okta has two types of authorization servers: the org authorization server and the custom authorization server. To learn more about each type of authorization server and when to use them, see [Authorization servers](https://developer.okta.com/docs/concepts/auth-servers/).
You can [create multiple custom authorization servers](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-an-authorization-server) within a single Okta org that you can use to protect your own resource servers. Within each authorization server, define your own custom OAuth 2.0 scopes, claims, and access policies to support authorization for your APIs.
- name: GlobalTokenRevocation
x-displayName: Global Token Revocation
description: The Global Token Revocation API provides a comprehensive solution for managing security across multiple applications and services. This API extends beyond the standard OAuth 2.0 token revocation, enabling the revocation of SSWS tokens and facilitating IdP-initiated sign-out processes.
- name: OrgAS
x-displayName: Org Authorization Server
description: |-
Every Okta org comes with a built-in authorization server called the org authorization server. Use the org authorization server to perform SSO with Okta for your OpenID Connect apps or to get an access token for the Okta APIs. You can't customize this authorization server with regards to audience, claims, policies, or scopes. Additionally, the resulting access token's issuer is `https://{yourOktaDomain}`, which indicates that only Okta can consume or validate it. The access token can't be used or validated by your own applications.
> **Note:** Okta has two types of authorization servers: the org authorization server and the custom authorization server. To learn more about each type of authorization server and when to use them, see [Authorization servers](https://developer.okta.com/docs/concepts/auth-servers/).
externalDocs:
description: Find more info here
url: https://developer.okta.com
paths:
/.well-known/openid-configuration:
get:
summary: Retrieve the OpenID Connect metadata
description: Returns OpenID Connect metadata for the Okta org authorization server. Clients use this information to programmatically configure their interactions with Okta.
operationId: getWellKnownOpenIDConfiguration
parameters:
- $ref: '#/components/parameters/queryClientId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/OidcMetadata'
examples:
OpenID Connect Metadata:
$ref: '#/components/examples/OrgASOidcMetadata'
'400':
$ref: '#/components/responses/Error400InvalidClientId'
tags:
- OrgAS
x-okta-lifecycle:
isCorsEnabled: true
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/authorize:
get:
summary: /authorize
description: |-
This is a starting point for browser-based OpenID Connect flows such as the implicit and authorization code flows. This request authenticates the user and returns tokens along with an authorization grant to the client application as a part of the callback response.
> **Note:** Requests to the `/authorize` endpoint should redirect the browser (user agent) to the endpoint. You can't use AJAX with this endpoint. Example responses are intentionally omitted, but include displaying a sign-in prompt, redirecting to the client application, or displaying an error.
operationId: authorize
parameters:
- name: acr_values
in: query
description: |-
An optional parameter that can be included in the authentication request. This parameter increases the level of user assurance.
> **Note:** Multiple space-delimited values may be provided. The authorization server will choose one and reflect the chosen value in any resulting tokens.
schema:
$ref: '#/components/schemas/AcrValue'
- name: client_id
in: query
required: true
description: Obtained during either manual client registration or through the [Dynamic Client Registration API](/openapi/okta-oauth/oauth/tag/Client/). It identifies the client and must match the value preregistered in Okta.
schema:
type: string
- name: code_challenge
in: query
description: A challenge for [PKCE](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/). The challenge is verified in the access token request.
schema:
type: string
- name: code_challenge_method
in: query
description: Method used to derive the code challenge for [PKCE](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/).
schema:
$ref: '#/components/schemas/CodeChallengeMethod'
- name: display
in: query
description: The `display` parameter to be passed to the external Identity Provider when performing [social login](https://developer.okta.com/docs/concepts/identity-providers/).
schema:
type: string
- name: enroll_amr_values
in: query
description: |-
A space-delimited list of values indicating which authenticators to enroll in.
* If the `enroll_amr_values` parameter is specified, then the value for `prompt` must be `enroll_authenticator`.
* The parameter value is space-delimited, for example, `pwd sms okta_verify` is a valid request parameter value. You are prompted in the order of the amr values provided.
schema:
$ref: '#/components/schemas/AmrValue'
- name: idp_scope
in: query
description: An Okta Extension to the OpenID specification. A space-delimited list of scopes to be provided to the external Identity Provider when performing [social login](https://developer.okta.com/docs/concepts/identity-providers/). These scopes are used in addition to the scopes already configured for the Identity Provider.
schema:
type: string
- name: idp
in: query
description: An Okta Extension to the OpenID Specification. The ID of the Identity Provider to use if there's no Okta Session.
schema:
type: string
- name: login_hint
in: query
description: A username to pre-populate if prompting for authentication
schema:
type: string
- name: max_age
in: query
description: Allowable elapsed time, in seconds, since the last time the end user was actively authenticated by Okta.
schema:
type: integer
- name: nonce
in: query
description: A value that is returned in the ID token. It is used to mitigate replay attacks. The value is required for Implicit and Hybrid flows, but optional for Auth Code flows. See [OIDC Specs](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
schema:
type: string
- name: prompt
in: query
description: |-
If no `prompt` parameter is specified, the standard behavior occurs:
* If an Okta session already exists and meets the assurance requirements of the app, the user is silently authenticated. Otherwise, the user is prompted to authenticate.
* If scopes are requested that require consent and consent isn't yet given by the authenticated user, the user is prompted to give consent.
schema:
$ref: '#/components/schemas/Prompt'
- name: redirect_uri
in: query
required: true
description: Callback location where the authorization code or tokens should be sent. It must match the value preregistered in Okta during client registration.
schema:
type: string
- name: response_type
in: query
required: true
description: Any combination of `code`, `token`, and `id_token`. The combination determines the [flow](https://developer.okta.com/docs/concepts/oauth-openid/#choose-an-oauth-2-0-flow).
schema:
$ref: '#/components/schemas/ResponseTypesSupported'
- name: response_mode
in: query
description: |-
How the authorization response should be returned. If `id_token` or `token` is specified in the `response_type`, then `query` isn't allowed as a response mode. Defaults to `fragment` in implicit and hybrid flows.
The `Referrer-Policy` header is automatically included in the response when either the fragment or query parameter values are used. The header is set to `Referrer-Policy: no-referrer`.
schema:
$ref: '#/components/schemas/ResponseMode'
- name: request_uri
in: query
description: Location where the authorization request payload data is referenced in an authorization request to the `/authorize` endpoint. This is returned from a Pushed Authorization Request at the `/par` endpoint.
schema:
type: string
- name: request
in: query
description: |-
A JWT created by the client that enables requests to be passed as a single, self-contained parameter.
* You must sign the JWT using either the app's client secret or a private key whose public key is registered on the app's JWKSet.
* The JWT can't be encrypted.
> **Note:** See [Build a JWT for client authentication](https://developer.okta.com/docs/guides/build-self-signed-jwt/) for information on how to build a JWT.
* Okta supports the [HMAC](https://tools.ietf.org/html/rfc7518#section-3.2), [RSA](https://tools.ietf.org/html/rfc7518#section-3.3) and [ECDSA](https://tools.ietf.org/html/rfc7518#section-3.4) signature algorithms. HMAC signatures require that the client has a `token_endpoint_auth_method` that uses a `client_secret`. RSA and ECDSA signatures requires that the client registers a public key.
* We recommend that you don't duplicate any request parameters in both the JWT and the query URI itself. However, you can do so with `state`, `nonce`, `code_challenge`, and `code_challenge_method`. In those cases, the values in the JWT overrides the query URI values.
* Okta validates the `request` parameter in the following ways:
1. `iss` is required and must be the `client_id`.
2. `aud` is required and must be the same value as the Authorization Server issuer that mints the ID or access token. This value is published in the metadata for your Authorization Server.
3. JWT lifetime is evaluated using the `iat` and `exp` claims, if present. If the JWT is expired or not yet valid, Okta returns an `invalid_request_object` error. Okta rejects JWTs that expire more than one hour in the future.
4. Okta rejects the JWT if the `jti` claim is present and it has already been processed.
schema:
type: string
- name: scope
in: query
required: true
description: A space-delimited string of scopes requested
schema:
type: string
- name: sessionToken
in: query
description: Okta one-time session token. This is an Okta extension to the OpenID specification. The `sessionToken` allows an API-based user sign-in flow.
schema:
type: string
- name: state
in: query
required: true
description: |-
A value to be returned with the token. The client application can use it to remember the state of its interaction with the end user at the time of the authentication call. It can contain alphanumeric, comma, period, underscore, and hyphen characters.
Okta requires the OAuth 2.0 `state` parameter on all requests to the `/authorize` endpoint to prevent cross-site request forgery (CSRF).
The OAuth 2.0 specification [requires](https://tools.ietf.org/html/rfc6749#section-10.12) that clients protect their redirect URIs against CSRF by sending a value in the authorize request that binds the request to the user-agent's authenticated state.
Using the `state` parameter is also a countermeasure to several other known attacks as outlined in [OAuth 2.0 Threat Model and Security Considerations](https://tools.ietf.org/html/rfc6819).
schema:
type: string
responses:
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
tags:
- OrgAS
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/bc/authorize:
post:
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: false
SKUs: []
summary: /bc/authorize
description: |-
This endpoint returns a unique identifier (`auth_req_id`) that identifies the authentication flow while it tries to authenticate the user in the background. This `auth_req_id` value is used in subsequent token requests to the `/token` endpoint.
> **Note:** The `/bc/authorize` endpoint requires client authentication. The method is configured per client application. See [Client authentication methods](/openapi/okta-oauth/guides/client-auth/) for more information.
operationId: bcAuthorize
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BackchannelAuthorizeRequest'
examples:
Request with `login_hint`:
$ref: '#/components/examples/BCAuthorizeRequestLoginHintExample'
Request with `id_token_hint`:
$ref: '#/components/examples/BCAuthorizeRequestIdTokenHintExample'
Request with signed `request`:
$ref: '#/components/examples/BCAuthorizeSignedRequestExample'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BackchannelAuthorizeResponse'
examples:
Back Response:
$ref: '#/components/examples/BackchannelAuthorizeResponseExample'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Multiple Client Credentials Provided:
$ref: '#/components/examples/OAuthError400InvalidRequest_MultipleClientCreds'
Missing Scopes:
$ref: '#/components/examples/OAuthError400InvalidScope_MissingScopes'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Missing Client Credentials:
$ref: '#/components/examples/OAuthError401InvalidClient_NoCreds'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
/oauth2/v1/challenge:
x-okta-lifecycle:
lifecycle: LIMITED_GA
isGenerallyAvailable: false
SKUs:
- Okta Identity Engine
post:
summary: /challenge
description: |-
Initiates the challenge of subsequent factor(s) in a Direct Authentication flow after the token endpoint has responded with 'mfa_required'. This endpoint is optional if the client is able to proceed without it, for example, when the client knows it needs to follow up with an OTP and can prompt the end user for one.
> **Note:** The `/challenge` endpoint requires client authentication. The method is configured per client application. See [Client authentication methods](/openapi/okta-oauth/guides/client-auth/).
operationId: challenge
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ChallengeRequest'
examples:
challengeRequestOob:
$ref: '#/components/examples/ChallengeRequestOobExample'
challengeRequestSms:
$ref: '#/components/examples/ChallengeRequestOobSmsExample'
challengeRequestVoice:
$ref: '#/components/examples/ChallengeRequestOobVoiceExample'
challengeRequestOtp:
$ref: '#/components/examples/ChallengeRequestOtpExample'
responses:
'200':
description: The next factor type to challenge is returned and in the case of out-of-band factors, any information needed for the out-of-band transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeResponse'
examples:
challengeResponseOtp:
$ref: '#/components/examples/ChallengeResponseMfaOtpExample'
challengeResponseOob:
$ref: '#/components/examples/ChallengeResponseMfaOobExample'
challengeResponseOvNmc:
$ref: '#/components/examples/ChallengeResponseOktaVerifyNumberMatchChallengeExample'
challengeResponseSms:
$ref: '#/components/examples/ChallengeResponseSmsExample'
challengeResponseVoice:
$ref: '#/components/examples/ChallengeResponseVoiceExample'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
invalidMfaToken:
$ref: '#/components/examples/ChallengeErrorInvalidMfaToken'
grantTypeDisabled:
$ref: '#/components/examples/OobAuthenticateErrorGrantTypeDisabled'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
invalidClientSecret:
$ref: '#/components/examples/OobAuthenticateErrorInvalidClientSecret'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
authenticatorCannotBeUsed:
$ref: '#/components/examples/ChallengeErrorInvalidMfaToken'
invalidChallengeType:
$ref: '#/components/examples/ChallengeErrorInvalidChallengeType'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
userRateLimit:
$ref: '#/components/examples/OobAuthenticateErrorRateLimit'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
/oauth2/v1/clients:
get:
summary: List all Client Applications
description: Lists all the client applications with pagination
operationId: listClients
parameters:
- $ref: '#/components/parameters/queryAfter'
- $ref: '#/components/parameters/queryLimit'
- name: q
in: query
schema:
type: string
description: |-
Searches the `client_name` property of clients for matching value.
> **Note:** Search currently performs a `startsWith` match, but this is an implementation detail and may change without notice.
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Client'
examples:
All Clients:
$ref: '#/components/examples/ListClientsResponse'
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.read
tags:
- Client
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
post:
summary: Register a Client Application
description: |-
Registers a new client application
> **Note:** You can create apps on the Apps endpoint (`/api/v1/apps`) and default to `consent_method=TRUSTED`, while those created with Dynamic Client Registration (`/oauth2/v1/clients`) default to `consent_method=REQUIRED`.
> **Note:** If you want to specify the `client_id` or `client_secret`, you can use Apps API to create or update a client Application.
Different Application types have different valid values for the corresponding grant type:
| Application Type | Valid Grant Type | Requirements |
| :---------------- | :------------------------------------------------------------------------- | :--------------------------------------------- |
| `browser` | `authorization_code`, `implicit`, `urn:ietf:params:oauth:grant-type:saml2-bearer`. The following grant types are <x-lifecycle class="oie"></x-lifecycle>only : `urn:okta:params:oauth:grant-type:otp`, `urn:okta:params:oauth:grant-type:oob`, `http://auth0.com/oauth/grant-type/mfa-otp`, `http://auth0.com/oauth/grant-type/mfa-oob` | |
| `native` | `authorization_code`, `implicit`, `password`, `refresh_token`, `urn:ietf:params:oauth:grant-type:saml2-bearer`. The following grant types are <x-lifecycle class="oie"></x-lifecycle>only : `urn:okta:params:oauth:grant-type:otp`, `urn:okta:params:oauth:grant-type:oob`, `http://auth0.com/oauth/grant-type/mfa-otp`, `http://auth0.com/oauth/grant-type/mfa-oob` | Must have at least `authorization_code` |
| `service` | `client_credentials`, `urn:ietf:params:oauth:grant-type:saml2-bearer`. The following grant types are <x-lifecycle class="oie"></x-lifecycle>only : `urn:okta:params:oauth:grant-type:otp`, `urn:okta:params:oauth:grant-type:oob`, `http://auth0.com/oauth/grant-type/mfa-otp`, `http://auth0.com/oauth/grant-type/mfa-oob` | Works with OAuth 2.0 flow (not OpenID Connect) |
| `web` | `authorization_code`, `implicit`, `refresh_token`, `client_credentials`(*), `urn:ietf:params:oauth:grant-type:saml2-bearer`. The following grant types are <x-lifecycle class="oie"></x-lifecycle>only : `urn:okta:params:oauth:grant-type:otp`, `urn:okta:params:oauth:grant-type:oob`, `http://auth0.com/oauth/grant-type/mfa-otp`, `http://auth0.com/oauth/grant-type/mfa-oob` | Must have at least `authorization_code` |
> **Note:** The `client_credentials` grant with a web Application type allows you to use one `client_id` for an Application that needs to make user-specific calls and back-end calls for data.
> **Note:** The `grant_types` and `response_types` values described above are partially orthogonal, as they refer to arguments passed to different endpoints in the [OAuth 2.0 protocol](https://tools.ietf.org/html/rfc6749). However, they are related in that the `grant_types` available to a client influence the `response_types` that the client is allowed to use and vice versa. For instance, a `grant_types` value that includes `authorization_code` implies a `response_types` value that includes `code`, as both values are defined as part of the OAuth 2.0 Authorization Code grant.
operationId: createClient
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientRequestWeb'
Service Client with JWKS:
$ref: '#/components/examples/ClientRequestServiceJwks'
Service Client with jwks_uri:
$ref: '#/components/examples/ClientRequestServiceJwksUri'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientResponseWeb'
Service Client with JWKS:
$ref: '#/components/examples/ClientResponseServiceJwks'
Service Client with jwks_uri:
$ref: '#/components/examples/ClientResponseServiceJwksUri'
'400':
$ref: '#/components/responses/ErrorInvalidClientMetadata400'
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.register
tags:
- Client
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/clients/{clientId}:
parameters:
- $ref: '#/components/parameters/pathClientId'
get:
summary: Retrieve a Client application
description: Retrieves a Client application by `clientId`
operationId: getClient
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientResponseWeb'
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'404':
$ref: '#/components/responses/ErrorResourceNotFound404'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.read
tags:
- Client
x-okta-lifecycle:
isCorsEnabled: true
lifecycle: GA
isGenerallyAvailable: true
put:
summary: Replace a Client Application
description: |-
Replaces the settings for a client application.
> **Note:** You must specifiy all settings when you update a client Application. Partial updates aren't supported. If any settings are missing when you update a client application, the update fails. The exceptions are that you can't include `client_secret_expires_at` or `client_id_issued_at` in the request, and you can omit the `client_secret`.
operationId: replaceClient
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientRequestWebUpdate'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientResponseWebUpdate'
'400':
$ref: '#/components/responses/ErrorInvalidClientMetadata400'
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'404':
$ref: '#/components/responses/ErrorResourceNotFound404'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.manage
tags:
- Client
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
delete:
summary: Delete a Client Application
description: Deletes a client application
operationId: deleteClient
responses:
'204':
description: No Content
content: {}
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'404':
$ref: '#/components/responses/ErrorResourceNotFound404'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.manage
tags:
- Client
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/clients/{clientId}/lifecycle/newSecret:
parameters:
- $ref: '#/components/parameters/pathClientId'
post:
summary: Generate a new client secret
description: |-
Generates a new client secret for the specified client Application.
> **Note:** This operation only applies to client Applications that use the `client_secret_post` or `client_secret_basic` method for token endpoint authorization.
operationId: generateNewClientSecret
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Client'
examples:
Web Client:
$ref: '#/components/examples/ClientResponseWebUpdateNewSecret'
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'404':
$ref: '#/components/responses/ErrorResourceNotFound404'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.clients.manage
tags:
- Client
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/device/authorize:
post:
summary: /device/authorize
description: Returns a user code, device code, activation link, and QR code activation link
operationId: deviceAuthorize
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DeviceAuthorizeRequest'
responses:
'200':
description: Based on the type of token and whether it is active, the returned JSON contains a different set of information.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceAuthorizeResponse'
examples:
Device Authorize:
$ref: '#/components/examples/DeviceAuthorizeResponseExample'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Missing Scopes:
$ref: '#/components/examples/OAuthError400InvalidScope_MissingScopes'
Multiple Client Credentials Provided:
$ref: '#/components/examples/OAuthError400InvalidRequest_MultipleClientCreds'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Missing Client Credentials:
$ref: '#/components/examples/OAuthError401InvalidClient_NoCreds'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
x-okta-lifecycle:
isCorsEnabled: true
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/global-token-revocation:
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: false
SKUs: []
post:
summary: Initiate the global revocation of all tokens and sessions
description: Initiates the global revocation of all tokens and sessions for a specified user enabling external Identity Providers to trigger a comprehensive sign-out process. This includes executing IdP-initiated sign-out flows across all applications that are using global token revocation and requiring users to re-authenticate to access protected resources.
operationId: globalTokenRevocation
x-codegen-request-body-name: body
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalTokenRevocationRequest'
examples:
GlobalTokenRevocationRequest:
$ref: '#/components/examples/GlobalTokenRevocationRequestExample'
required: true
responses:
'204':
description: No Content
content: {}
'400':
description: Bad Request
content: {}
'403':
$ref: '#/components/responses/ErrorAccessDenied403'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- apiToken: []
- oauth2:
- okta.universalLogout.manage
tags:
- GlobalTokenRevocation
/oauth2/v1/introspect:
post:
summary: /introspect
description: |-
This endpoint takes an access token, ID token, refresh token, or device secret and returns a boolean that indicates whether it is active. If the token is active, additional data about the token is also returned. If the token is invalid, expired, or revoked, it is considered inactive.
Be sure that you are using the `/introspect` endpoint of the same authorization server that you used to create the token.
> **Note:** The `/introspect` endpoint requires client authentication. The method is configured per client application. See [Client authentication methods](/openapi/okta-oauth/guides/client-auth/). For public clients (such as single-page and mobile apps) that don't have a `client_secret`, include the `client_id` as a query parameter when calling the `/introspect` endpoint. Make sure that you aren't passing the Authorization header in the request.
operationId: introspect
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectionRequest'
responses:
'200':
description: Based on the type of token and whether it is active, the returned JSON contains a different set of information.
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectionResponse'
examples:
Access Token:
$ref: '#/components/examples/IntrospectionAccessToken'
Refresh Token:
$ref: '#/components/examples/IntrospectionRefreshToken'
Inactive Token:
$ref: '#/components/examples/IntrospectionInactiveToken'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Missing `token` Parameter:
$ref: '#/components/examples/OAuthError400InvalidRequest_MissingToken'
Client Assertion Type Incorrect for JWT Request:
$ref: '#/components/examples/OAuthError400InvalidRequest_AssertionTypeInvalid'
Multiple Client Credentials Provided:
$ref: '#/components/examples/OAuthError400InvalidRequest_MultipleClientCreds'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
Missing Client Credentials:
$ref: '#/components/examples/OAuthError401InvalidClient_NoCreds'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
x-okta-lifecycle:
isCorsEnabled: true
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/keys:
get:
summary: /keys
description: |-
Returns a JSON Web Key Set (JWKS) that contains the public keys that can be used to verify the signatures of tokens that you receive from your authorization server.
> **Note:** Looking for how to obtain the `jwks_uri` for your org authorization server? See the [well-known OpenID Connect metadata endpoint](/openapi/okta-oauth/oauth/tag/OrgAS/#tag/OrgAS/operation/getWellKnownOpenIDConfiguration).
Any of the two or three keys listed are used to sign tokens. The order of keys in the result doesn't indicate which keys are used.
These keys can be used to locally validate JWTs returned by Okta. Standard open-source libraries are available for every major language to perform [JWS](https://datatracker.ietf.org/doc/html/rfc7515) signature validation.
> **Note:** The information returned from this endpoint could lag slightly, but will eventually be up-to-date.
> **Note:** Okta returns [standard HTTP Cache-Control headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for applicable JWKS endpoints. Ensure that you respect the cache header directives, as they are updated based on the time of the request.
For more information on key rotation and best practices, see [JSON Web Key Set](/openapi/okta-oauth/guides/overview/#json-web-key-set).
operationId: oauthKeys
parameters:
- name: client_id
in: query
description: The `client_id` of a Client application. Providing this optional parameter will include any public keys associated with the signing keys of the application.
schema:
type: string
responses:
'200':
description: Success
headers:
Cache-Control:
schema:
type: string
example: max-age=3832304, must-revalidate
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthKeys'
examples:
User information:
$ref: '#/components/examples/OAuthKeysExample'
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
tags:
- OrgAS
x-okta-lifecycle:
isCorsEnabled: true
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/logout:
get:
summary: /logout
description: |-
Use this operation to sign a user out by removing their Okta browser session.
This endpoint takes an ID token and logs the user out of Okta if the subject matches the current Okta session. A `post_logout_redirect_uri` may be specified to redirect the browser after the logout is performed. Otherwise, the browser is redirected to the Okta sign-in page. See [Sign users](https://developer.okta.com/docs/guides/sign-users-out/) out for more information.
If no Okta session exists, this endpoint has no effect and the browser is redirected immediately to the Okta sign-in page or the `post_logout_redirect_uri` (if specified).
If the ID token passed using `id_token_hint` is invalid, the browser is redirected to an error page.
If the ID token is valid, but expired, and the subject matches the current Okta session, a logout request signs the user out and redirects the browser to the `post_logout_redirect_uri`.
> **Note:** When making requests to the `/logout` endpoint, the browser (user agent) should be redirected to the endpoint. You can't use AJAX with this endpoint. We may load an interstitial to do client-side logic before redirecting to the `post_logout_redirect_uri`, or login page if no redirect is provided.
operationId: logout
parameters:
- name: id_token_hint
in: query
description: A valid ID token with a subject that matches the current session.
schema:
type: string
required: true
- name: post_logout_redirect_uri
in: query
description: Location to redirect to after the logout is performed. It must match the value preregistered in Okta during client registration.
schema:
type: string
- $ref: '#/components/parameters/queryState'
responses:
'200':
description: Successful logout
content: {}
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
tags:
- OrgAS
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
post:
summary: /logout
description: |-
Use this operation to sign a user out by removing their Okta browser session. This is the recommended method over GET as you can wrap the parameters in the request body.
This endpoint uses the ID token to verify that the subject matches the current Okta session, and then signs the user out. You can specify a `post_logout_redirect_uri` to redirect the browser after the user signs out. Otherwise, the browser is redirected to the Okta sign-in page. See [Sign users out](https://developer.okta.com/docs/guides/sign-users-out/).
If no Okta session exists, this endpoint has no effect and the browser is redirected immediately to the Okta sign-in page or the `post_logout_redirect_uri` (if specified).
If the ID token passed using `id_token_hint` is invalid, the browser is redirected to an error page.
If the ID token is valid, but expired, and the subject matches the current Okta session, a logout request signs the user out and redirects the browser to the `post_logout_redirect_uri`.
> **Note:** When making requests to the `/logout` endpoint, the browser (user agent) should be redirected to the endpoint. You need to make a POST request from a form. A POST request to this endpoint from the backend doesn't completely terminate the session.
operationId: logoutWithPost
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LogoutWithPost'
examples:
LogoutRequest:
$ref: '#/components/examples/LogoutRequestExample'
responses:
'200':
description: Successful logout
content: {}
'429':
$ref: '#/components/responses/ErrorTooManyRequests429'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
x-okta-lifecycle:
lifecycle: GA
isGenerallyAvailable: true
/oauth2/v1/oob-authenticate:
x-okta-lifecycle:
lifecycle: LIMITED_GA
isGenerallyAvailable: false
SKUs:
- Okta Identity Engine
post:
summary: /oob-authenticate
description: |-
Initiates direct authentication with an out-of-band authenticator
> **Note:** The `/oob-authenticate` endpoint requires client authentication. The method is configured per client application. See [Client authentication methods](/openapi/okta-oauth/guides/client-auth/).
operationId: oob-authenticate
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OobAuthenticateRequest'
examples:
oobRequest:
$ref: '#/components/examples/OobAuthenticateRequestExample'
oobSmsRequest:
$ref: '#/components/examples/OobAuthenticateSmsRequestExample'
oobVoiceRequest:
$ref: '#/components/examples/OobAuthenticateVoiceRequestExample'
responses:
'200':
description: Out-of-band authentication has successfully been initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/OobAuthenticateResponse'
examples:
ovPushResponse:
$ref: '#/components/examples/OobAuthenticateResponseExample'
ovNmcResponse:
$ref: '#/components/examples/OobAuthenticateResponseOktaVerifyNumberMatchChallengeExample'
smsResponse:
$ref: '#/components/examples/OobAuthenticateResponseSmsExample'
voiceResponse:
$ref: '#/components/examples/OobAuthenticateResponseVoiceExample'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
invalidChannelHint:
$ref: '#/components/examples/OobAuthenticateErrorInvalidChannelHint'
userNotAssigned:
$ref: '#/components/examples/OobAuthenticateErrorUserNotAssignedApp'
grantTypeDisabled:
$ref: '#/components/examples/OobAuthenticateErrorGrantTypeDisabled'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
invalidClientSecret:
$ref: '#/components/examples/OobAuthenticateErrorInvalidClientSecret'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
authenticatorCannotBeUsed:
$ref: '#/components/examples/OobAuthenticateErrorAuthenticatorCannotBeUsed'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
userRateLimit:
$ref: '#/components/examples/OobAuthenticateErrorRateLimit'
security:
- Client_authentication_client_secret_basic: []
- Client_authentication_client_secret_post: []
- Client_authentication_client_secret_jwt: []
- Client_authentication_private_key_jwt: []
tags:
- OrgAS
/oauth2/v1/par:
options:
summary: /par
description: |-
Use this operation to request the permitted communication options for the `/par` operation.
> **Note:** CORS is enforced on a per-client basis. This endpoint always returns CORS headers with the current Origin.
operationId: parOptions
parameters:
- in: header
name: Origin