{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/openapi/oag/guides/overview/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Okta Access Gateway API

\n

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.

\n

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.

\n
\n

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

\n
\n

Authentication

\n

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.

\n

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

\n
\n

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.

\n
\n

Header:

\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\"\n}
\n
\n

Payload:

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ClaimDescriptionType
issRequired. The issuer of the token. This value must be the same as the client_id of the application that you're accessing.String
subRequired. The subject of the token. This value must be the same as the client_id of the application that you're accessing.String
audRequired. The full URL of the resource that you're trying to access using the JWT to authenticate. For example: https://<oag-hostname>.String
expRequired. The token expiration time in seconds since January 1, 1970 UTC (UNIX timestamp), for example, 1555594819. This claim fails the request if the expiration time is more than one hour in the future or if the token is already expired.Integer
iatOptional. When the token was issued in seconds since January 1, 1970 UTC (UNIX timestamp), for example, 1555591219. If specified, it must be a time before the request is received.Integer
scopeRequired. The scopes requested with the AUTHN_TOKEN, which control access to Access Gateway resources.String
\n

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

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

The ACCESS_TOKEN is returned in the response.

\n

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

\n

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

\n
\n

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.

\n
\n

Scopes

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ScopeDescription
okta.oag.app.manageAllows the app to create and manage apps in your Access Gateway.
okta.oag.app.readAllows the app to read app details in your Access Gateway.
okta.oag.cert.readAllows the app to read certificate details.
okta.oag.idp.manageAllows the app to create and manage identity providers.
okta.oag.idp.readAllows the app to read identity providers.
","headings":[{"value":"Okta Access Gateway API","depth":1},{"value":"Authentication","depth":2},{"value":"Scopes","depth":2}]},"contentItem":{"data":{"lastModified":"2025-11-03T21:49:20.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":true,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"55be494c-0540-549a-9d7d-863ff52e80d4__redocly content/openapi/oag/guides/overview/","seo":{"title":"Okta Access Gateway API","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"openapi/oag/guides/overview.md","pageBaseUrl":"/openapi/oag/guides/overview","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Okta Access Gateway API","id":"okta-access-gateway-api"},{"depth":2,"value":"Authentication","id":"authentication"},{"depth":2,"value":"Scopes","id":"scopes"}]},"data":{"title":""},"catalogInfo":null,"link":"/openapi/oag/guides/overview/","sidebarName":"reference","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}