{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Introduction to the Okta Aerial API","description":"Okta Developer API Reference","siteUrl":"https://developer-okta.login.adsbillinghub.com","keywords":"okta, api reference docs","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"introduction-to-the-okta-aerial-api","__idx":0},"children":["Introduction to the Okta Aerial API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Okta Aerial is an administration service that enables multi-org management. Use the Aerial API to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add orgs to the Aerial account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Activate and deactivate orgs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["View subscribed products."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable products in specific orgs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"important-terms","__idx":1},"children":["Important terms"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Term"},"children":["Term"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aerial account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aerial org"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Products"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Okta-determined sets of features. Example products include:",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["P000052"]},": IT Products - SSO"]}," ",{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["P000131"]},": IT Products - MFA"]}," ",{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["P000139"]},": IT Products - Lifecycle Management with 1 OIN App"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"With the Okta Aerial API, you can view subscribed products for an Aerial account and enable a subset of products to orgs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Features"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Distinct pieces of functionality. Features are bundled within products but may also be offered separately, for example, Early Access features."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"aerial-sandbox-and-production-environments","__idx":2},"children":["Aerial sandbox and production environments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Okta provides the following environments to use with your Aerial account:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sandbox: Only connected to OP3 cells. Use for scale testing and repetitive testing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://aerial-sandbox-okta.login.adsbillinghub.com"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Production: Connected to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["okta.com"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["okta.preview.com"]},". Use to explore the Aerial API, or test net-new development. Link a preview org to your production instance."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://aerial-apac-okta.login.adsbillinghub.com"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":3},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To authenticate with the Aerial APIs, a super admin in the Aerial org must:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create an API client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain an access token with the correct scopes."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the JWT bearer token obtained from the client to make HTTP requests with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header. The header has a value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer {AUTH_TOKEN}"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/guides/implement-oauth-for-okta-serviceapp/-/main/#get-an-access-token"},"children":["Implement OAuth for Okta with a service app"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc9449"},"children":["Demonstrating Proof-of-Possession (DPoP)"]}," is supported but not required. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/guides/dpop/main/"},"children":["Configure OAuth 2.0 Demonstrating Proof-of-Possession"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scopes","__idx":4},"children":["Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Aerial API uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scopes"]}," attached to the authorization token to determine the level of access for different endpoints."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["okta.accounts.read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Grants read access to Aerial operations"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["okta.accounts.manage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Grants full access to Aerial operations"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"aerial-rate-limits","__idx":5},"children":["Aerial rate limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each Okta Aerial account has a rate limit of 10 concurrent requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the rate limit is exceeded, the Aerial API returns an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your use case requires a higher concurrency limit, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://support-okta.login.adsbillinghub.com"},"children":["Okta Support"]}," with your Aerial account details and a description of your workload to request a rate limit increase."]}]},"headings":[{"value":"Introduction to the Okta Aerial API","id":"introduction-to-the-okta-aerial-api","depth":1},{"value":"Important terms","id":"important-terms","depth":2},{"value":"Aerial sandbox and production environments","id":"aerial-sandbox-and-production-environments","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"Scopes","id":"scopes","depth":3},{"value":"Aerial rate limits","id":"aerial-rate-limits","depth":2}],"frontmatter":{"seo":{"title":"Introduction to the Okta Aerial API"}},"lastModified":"2026-02-25T19:30:46.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/openapi/aerial/guides/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}