OAuth 2.0 token lifecycle

Learn how the Hybrid Service acquires, caches, refreshes, and secures OAuth 2.0 access tokens for outbound requests.

When an Enterprise Connector-enabled endpoint is configured to use OAuth 2.0 Target Security, the Hybrid Service manages the OAuth 2.0 access token automatically.

Token lifecycle

  1. API Gateway receives the request and identifies that the target endpoint uses OAuth 2.0 Target Security.

  2. API Gateway passes the OAuth 2.0 configuration to the Hybrid Service.

  3. The Hybrid Service checks the in-memory token cache.

    • If a valid (non-expired) token exists, the cached token is used.
    • If no token exists or the token is nearing expiration, a new token is requested from the external authorization server.

  4. The Hybrid Service adds the Bearer token to the outbound request.

  5. The request is sent to the target API.

  6. If the target API returns HTTP 401, the Hybrid Service discards the cached token, requests a new token, and retries the request.

  7. The response is returned through API Gateway to the caller.

Token caching behavior

  • Access tokens are stored in memory only and are not persisted.
  • The token cache is thread-safe and shared across concurrent outbound requests.
  • Tokens are refreshed before expiration to reduce the risk of request failures.
  • After a Hybrid Service restart, tokens are acquired again when needed.
  • This design supports both Client Credentials and Resource Owner Password Credentials (ROPC) because both grant types use short-lived access tokens.

Security model

  • Communication with external authorization servers is secured by HTTPS.
  • Client secrets and passwords are stored securely and are not exposed in API responses or logs.
  • Token values are not logged. Only token lifecycle events are recorded.
  • Only users with the IONAPI-Administrator role can access the OAuth 2.0 configuration.