Okta Access Gateway API

The Okta Access Gateway API enables you to configure your Access Gateway configuration through API requests. For information about using Access Gateway through the Admin Console, see the Access Gateway documentation.

Access Gateway is a reverse proxy-based virtual appliance that protects on-premises applications that rely on HTTP headers, Kerberos tokens, and other legacy methods. It offers URL-based authentication and protects access to on-premises apps that don't support federation with user authentication and single sign-on capabilities of Okta. Since Access Gateway is behind the firewall, it lets external users access on-premises web-based apps without the need for traditional VPNs. When it's deployed, all browser traffic flows first to Access Gateway and then to the back-end protected app. This allows Access Gateway to monitor every request that a user accesses, perform authorization, and add the appropriate headers and tokens to the request.

Note: The Access Gateway API is available on version 2025.10.0 and later.

Authentication

To use Access Gateway APIs you must first enable the API on Access Gateway which generates a client ID and the private and public key pair. See Enable the Access Gateway API.

Using the private key retrieved from Access Gateway, sign a JSON Web Token (JWT) with the following header and payload:

Note: For information about creating and signing a JWT, see Build a JWT for Client Authentication and How to generate a JWT for Okta Access Gateway APIs.

Header:

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload:

{
  "iss": "<client_id>",
  "sub": "<client_id>",
  "aud": "https://<oag-hostname>",
  "exp": "<5 minutes into the future>",
  "iat": "<Current timestamp>",
  "scope": "<Scopes requested with the access token, which controls access to Access Gateway resources>"
}

See the following table for descriptions of the claims in the JWT payload:

The signed JWT is used as an AUTHN_TOKEN to retrieve the ACCESS_TOKEN. Send a request to the /api/v2/oauth/token endpoint with the request payload containing the following parameters as URL-encoded form data:

'grant_type': 'client_credentials'
'client_assertion_type': 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
'client_assertion': '<signed_jwt>'
'scope': '<Scopes requested with the access token, which controls access to Access Gateway resources>'

The ACCESS_TOKEN is returned in the response.

All calls to the Okta Access Gateway API need to have an HTTP Authorization header with a value of {ACCESS_TOKEN}.

For more information about the request for an ACCESS_TOKEN, see the Access Tokens API.

Note: Access tokens may expire at any time. Any code that uses access tokens must be prepared to handle HTTP 401 Unauthorized errors by creating a new AUTHN_TOKEN and requesting an ACCESS_TOKEN.

Scopes

Use the following scopes in your AUTHN_TOKEN to control access to Access Gateway resources: