1---
2layout: "api"
3page_title: "Okta - Auth Methods - HTTP API"
4sidebar_title: "Okta"
5sidebar_current: "api-http-auth-okta"
6description: |-
7  This is the API documentation for the Vault Okta auth method.
8---
9
10# Okta Auth Method (API)
11
12This is the API documentation for the Vault Okta auth method. For
13general information about the usage and operation of the Okta method, please
14see the [Vault Okta method documentation](/docs/auth/okta.html).
15
16This documentation assumes the Okta method is mounted at the `/auth/okta`
17path in Vault. Since it is possible to enable auth methods at any location,
18please update your API calls accordingly.
19
20## Create Configuration
21
22Configures the connection parameters for Okta. This path honors the
23distinction between the `create` and `update` capabilities inside ACL policies.
24
25| Method   | Path                         |
26| :--------------------------- | :--------------------- |
27| `POST`   | `/auth/okta/config`          |
28
29### Parameters
30
31- `org_name` `(string: <required>)` - Name of the organization to be used in the
32  Okta API.
33- `api_token` `(string: "")` - Okta API token. This is required to query Okta
34  for user group membership. If this is not supplied only locally configured
35  groups will be enabled.
36- `base_url` `(string: "")` -  If set, will be used as the base domain
37  for API requests.  Examples are okta.com, oktapreview.com, and okta-emea.com.
38- `ttl` `(string: "")` - Duration after which authentication will be expired.
39- `max_ttl` `(string: "")` - Maximum duration after which authentication will
40  be expired.
41- `bypass_okta_mfa` `(bool: false)` - Whether to bypass an Okta MFA request.
42  Useful if using one of Vault's built-in MFA mechanisms, but this will also
43  cause certain other statuses to be ignored, such as `PASSWORD_EXPIRED`.
44
45### Sample Payload
46
47```json
48{
49  "org_name": "example",
50  "api_token": "abc123"
51}
52```
53
54### Sample Request
55
56```
57$ curl \
58    --header "X-Vault-Token: ..." \
59    --request POST \
60    --data @payload.json \
61    http://127.0.0.1:8200/v1/auth/okta/config
62```
63
64## Read Configuration
65
66Reads the Okta configuration.
67
68| Method   | Path                         |
69| :--------------------------- | :--------------------- |
70| `GET`    | `/auth/okta/config`          |
71
72### Sample Request
73
74```
75$ curl \
76    --header "X-Vault-Token: ..." \
77    http://127.0.0.1:8200/v1/auth/okta/config
78```
79
80### Sample Response
81
82```json
83{
84  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
85  "lease_id": "",
86  "lease_duration": 0,
87  "renewable": false,
88  "data": {
89    "org_name": "example",
90    "api_token": "abc123",
91    "base_url": "okta.com",
92    "ttl": "",
93    "max_ttl": ""
94  },
95  "warnings": null
96}
97```
98
99## List Users
100
101List the users configured in the Okta method.
102
103| Method   | Path                         |
104| :--------------------------- | :--------------------- |
105| `LIST`   | `/auth/okta/users`           |
106
107### Sample Request
108
109```
110$ curl \
111    --header "X-Vault-Token: ..." \
112    --request LIST \
113    http://127.0.0.1:8200/v1/auth/okta/users
114```
115
116### Sample Response
117
118```json
119{
120  "auth": null,
121  "warnings": null,
122  "wrap_info": null,
123  "data": {
124    "keys": [
125      "fred",
126	    "jane"
127    ]
128  },
129  "lease_duration": 0,
130  "renewable": false,
131  "lease_id": ""
132}
133```
134
135## Register User
136
137Registers a new user and maps a set of policies to it.
138
139| Method   | Path                         |
140| :--------------------------- | :--------------------- |
141| `POST`   | `/auth/okta/users/:username` |
142
143### Parameters
144
145- `username` `(string: <required>)` - Name of the user.
146- `groups` `(array: [])` - List or comma-separated string of groups associated with the user.
147- `policies` `(array: [])` - List or comma-separated string of policies associated with the user.
148
149```json
150{
151  "policies": [
152    "dev",
153    "prod"
154  ]
155}
156```
157
158### Sample Request
159
160```
161$ curl \
162    --header "X-Vault-Token: ..." \
163    --request POST \
164    --data @payload.json \
165    http://127.0.0.1:8200/v1/auth/okta/users/fred
166```
167
168## Read User
169
170Reads the properties of an existing username.
171
172| Method   | Path                         |
173| :--------------------------- | :--------------------- |
174| `GET`   | `/auth/okta/users/:username` |
175
176### Parameters
177
178- `username` `(string: <required>)` - Username for this user.
179
180### Sample Request
181
182```
183$ curl \
184    --header "X-Vault-Token: ..." \
185    http://127.0.0.1:8200/v1/auth/okta/users/test-user
186```
187
188### Sample Response
189
190```json
191{
192  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
193  "lease_id": "",
194  "lease_duration": 0,
195  "renewable": false,
196  "data": {
197    "policies": [
198      "default",
199      "dev",
200    ],
201    "groups": []
202  },
203  "warnings": null
204}
205```
206
207## Delete User
208
209Deletes an existing username from the method.
210
211| Method   | Path                         |
212| :--------------------------- | :--------------------- |
213| `DELETE`   | `/auth/okta/users/:username` |
214
215### Parameters
216
217- `username` `(string: <required>)` - Username for this user.
218
219### Sample Request
220
221```
222$ curl \
223    --header "X-Vault-Token: ..." \
224    --request DELETE \
225    http://127.0.0.1:8200/v1/auth/okta/users/test-user
226```
227
228## List Groups
229
230List the groups configured in the Okta method.
231
232| Method   | Path                         |
233| :--------------------------- | :--------------------- |
234| `LIST`   | `/auth/okta/groups`           |
235
236### Sample Request
237
238```
239$ curl \
240    --header "X-Vault-Token: ..." \
241    --request LIST \
242    http://127.0.0.1:8200/v1/auth/okta/groups
243```
244
245### Sample Response
246
247```json
248{
249  "auth": null,
250  "warnings": null,
251  "wrap_info": null,
252  "data": {
253    "keys": [
254      "admins",
255      "dev-users"
256    ]
257  },
258  "lease_duration": 0,
259  "renewable": false,
260  "lease_id": ""
261}
262```
263
264## Register Group
265
266Registers a new group and maps a set of policies to it.
267
268| Method   | Path                         |
269| :--------------------------- | :--------------------- |
270| `POST`   | `/auth/okta/groups/:name` |
271
272### Parameters
273
274- `name` `(string: <required>)` - The name of the group.
275- `policies` `(array: [])` - The list or comma-separated string of policies associated with the group.
276
277```json
278{
279  "policies": [
280    "dev",
281    "prod"
282  ]
283}
284```
285
286### Sample Request
287
288```
289$ curl \
290    --header "X-Vault-Token: ..." \
291    --request POST \
292    --data @payload.json \
293    http://127.0.0.1:8200/v1/auth/okta/groups/admins
294```
295
296## Read Group
297
298Reads the properties of an existing group.
299
300| Method   | Path                         |
301| :--------------------------- | :--------------------- |
302| `GET`   | `/auth/okta/groups/:name`     |
303
304### Parameters
305
306- `name` `(string: <required>)` - The name for the group.
307
308### Sample Request
309
310```
311$ curl \
312    --header "X-Vault-Token: ..." \
313    http://127.0.0.1:8200/v1/auth/okta/groups/admins
314```
315
316### Sample Response
317
318```json
319{
320  "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
321  "lease_id": "",
322  "lease_duration": 0,
323  "renewable": false,
324  "data": {
325    "policies": [
326      "default",
327      "admin"
328    ]
329  },
330  "warnings": null
331}
332```
333
334## Delete Group
335
336Deletes an existing group from the method.
337
338| Method   | Path                         |
339| :--------------------------- | :--------------------- |
340| `DELETE`   | `/auth/okta/groups/:name` |
341
342### Parameters
343
344- `name` `(string: <required>)` - The name for the group.
345
346### Sample Request
347
348```
349$ curl \
350    --header "X-Vault-Token: ..." \
351    --request DELETE \
352    http://127.0.0.1:8200/v1/auth/okta/users/test-user
353```
354
355## Login
356
357Login with the username and password.
358
359| Method   | Path                         |
360| :--------------------------- | :--------------------- |
361| `POST`   | `/auth/okta/login/:username` |
362
363### Parameters
364
365- `username` `(string: <required>)` - Username for this user.
366- `password` `(string: <required>)` - Password for the authenticating user.
367
368### Sample Payload
369
370```json
371{
372  "password": "Password!"
373}
374```
375
376### Sample Request
377
378```
379$ curl \
380    --request POST \
381    --data @payload.json \
382    http://127.0.0.1:8200/v1/auth/okta/login/fred
383```
384
385### Sample Response
386
387```javascript
388{
389  "lease_id": "",
390  "renewable": false,
391  "lease_duration": 0,
392  "data": null,
393  "warnings": null,
394  "auth": {
395    "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
396    "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
397    "policies": ["default"],
398    "metadata": {
399      "username": "fred",
400      "policies": "default"
401    },
402  },
403  "lease_duration": 7200,
404  "renewable": true
405}
406 ```
407