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