Introduction to the Okta Aerial API

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.

Important terms

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 - SSO
  • P000131: IT Products - MFA
  • P000139: IT Products - Lifecycle Management with 1 OIN App

    • With 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.

    Aerial sandbox and production environments

    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.com

    • Production: Connected to okta.com and okta.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

    Authentication

    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.

    Scopes

    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