Okta Aerial is an administration service that enables multi-org management. Use the Aerial API to:
- Add orgs to the Aerial account.
- Activate and deactivate orgs.
- View subscribed products.
- Enable products in specific orgs.
| Term | Description |
|---|---|
| Aerial account | The management layer around multiple orgs within Okta. The Aerial account lives outside of your orgs and can manage any production or preview org linked to the Aerial account. |
| Aerial org | Holds the authorization server for all Aerial API actions in any org in the Aerial account. Choose one org to permanently serve as the Aerial org. Super admins can create API clients in the org to access the Aerial account. The org also contains all System Log events associated with Okta Aerial actions. |
| Products | Okta-determined sets of features. Example products include:P000052: IT Products - SSOP000131: IT Products - MFAP000139: IT Products - Lifecycle Management with 1 OIN AppWith the Okta Aerial API, you can view subscribed products for an Aerial account and enable a subset of products to orgs. |
| Features | Distinct pieces of functionality. Features are bundled within products but may also be offered separately, for example, Early Access features. |
Okta provides the following environments to use with your Aerial account:
Sandbox: Only connected to OP3 cells. Use for scale testing and repetitive testing.
https://aerial-sandbox.okta.comProduction: Connected to
okta.comandokta.preview.com. Use to explore the Aerial API, or test net-new development. Link a preview org to your production instance.https://aerial-apac.okta.com
To authenticate with the Aerial APIs, a super admin in the Aerial org must:
- Create an API client.
- Obtain an access token with the correct scopes.
Use the JWT bearer token obtained from the client to make HTTP requests with an Authorization header. The header has a value of Bearer {AUTH_TOKEN}.
See Implement OAuth for Okta with a service app.
Demonstrating Proof-of-Possession (DPoP) is supported but not required. See Configure OAuth 2.0 Demonstrating Proof-of-Possession.
The Aerial API uses scopes attached to the authorization token to determine the level of access for different endpoints.
| Scope | Description |
|---|---|
okta.accounts.read | Grants read access to Aerial operations |
okta.accounts.manage | Grants full access to Aerial operations |
Each Okta Aerial account has a rate limit of 10 concurrent requests.
A concurrent request is any in-flight HTTP request to the Aerial API for a given Aerial account in a given environment (sandbox or production). If more than 10 requests are open at the same time, additional requests are throttled until existing requests complete.
When the rate limit is exceeded, the Aerial API returns an HTTP 429 Too Many Requests response. Clients should treat this as a temporary error and can safely retry the request after reducing concurrency or adding a backoff delay.
If your use case requires a higher concurrency limit, contact Okta Support with your Aerial account details and a description of your workload to request a rate limit increase.