the already-obtained access token
object containing the tokens
Dispose of the instance when it is no longer needed (a host that creates instances over its lifetime, or exits): cancel the auto refresh timer, clear the refresh and credential handlers, forget the credentials, and end the user session only when this instance created it and did not share it. A session that came out of the token cache or was stored in it may be in use by other processes and is left to expire; the same goes for a session that this instance did not create. With the token cache switched off, the sessions that the instance created are ended.
A disposed instance does not log in by itself any more: no timer fires and a request that finds a credential stale
fails instead of logging in. Calling getTokens(), getTokensInteractive() or applyAccessToken() makes it work
again. A login that is still running when dispose() is called is not interrupted and its session is not ended.
A failed logout request is reported in the result and never thrown, so that a shutdown goes on.
what happened to the session
Get the access profile of the current session: what the credential the library holds can do on a Cloud tenant. For an interactive login (a browser login with authorization code, or a device authorization login) and for a service account it says which scopes the token carries, whether the session can be refreshed, whether the token carries an Access Management session, which areas of the API are reachable and which are not and why (for example "the login did not request a scope that the client offers", "the access token of a device authorization login carries no Access Management session"), and what the library did differently from its defaults to make the login succeed. Every statement names its basis: what the token says, or a measured constant of the library with the date it was measured. The profile is computed from the token and the state, with no network call, so a session reused from the session cache has one too.
What the profile says for the three interactive sessions of the built-in client (measured on a Cloud development tenant on 2026-11-14, one read call per area; "scope not requested": the client offers the scope, the login did not ask for it):
| Area | Browser login, default scopes (fr:am:* fr:idm:*) |
Browser login, all five scopes | Device login, without fr:am:* |
|---|---|---|---|
| Access Management | reachable | reachable | not reachable: no Access Management session |
| Identity Management | reachable | reachable | reachable |
| Environment secrets and variables | no: scope not requested | reachable | reachable |
| Governance, configuration promotion, release information, certificates, custom domains, content security policy, cookie domains, SSO cookie, direct configuration session, telemetry | no: the client does not offer the scope | no: same | no: same |
| Admin federation | no: the exchange client refuses the scope | no: same | no: same |
| PingFederate administration | no: an interactive login gets no PingFederate token | no: same | no: same |
The five scopes are fr:am:* fr:idm:* fr:idc:esv:read fr:idc:esv:update fr:idc:monitoring:*. None of these
sessions has a refresh token; the access token lives 30 minutes.
the profile, or undefined if the session is not a Cloud session with an access token (a user session, Amster, ForgeOps, classic, no login yet)
Get tokens and store them in State
OptionalforceLoginAsUser: boolean
true to force login as user even if a service account or Amster account is available (default: false)
OptionalautoRefresh: boolean
true to automatically refresh tokens before they expire (default: true)
Optionaltypes: string[]
Array of supported deployment types. The function will throw an error if an unsupported type is detected (default: ['classic', 'cloud', 'forgeops'])
OptionalcallbackHandler: CallbackHandler
fills callback input in place, synchronously or asynchronously; returned or resolved values are ignored (see CallbackHandler)
OptionaluseDeviceFlow: boolean
only consulted when a loaded connection profile prefers browser login (preferredCredential: 'browser', or the legacy authMode: 'interactive' for a profile predating that field) — falls back to the profile's own preferredDeviceFlow when not explicitly passed; see getTokensInteractive() (default: false)
OptionalpromptHandler: BrowserLoginPromptHandler
required only when a loaded connection profile prefers browser login; every other case ignores it
OptionalcredentialOverride: "svcacct" | "user" | "browser" | "amster"object containing the tokens
Get tokens via a real interactive browser login (loopback-redirect or
device-authorization grant) instead of a CLI-driven password/service-
account/Amster login. Alongside getTokens(), not a replacement for it.
browser-login options
object containing the tokens
Whether a browser-login session is cached for the host and would be
reused: the cache holds one for the host's full URL (an alias or a unique
substring of a saved profile is resolved to it) that is still fresh,
with the same 30 seconds of headroom the cache read requires. Reads the
local cache file only: no network call, nothing decrypted, nothing
written to state. A session that passes can still be refused by the
server later; getTokens() then falls back to its own login.
Intended for callers that decide whether a command still needs input (a prompt, a connection form) before they log in.
host URL, unique substring or alias of a saved connection profile
true if a fresh browser-login session is cached for the host
List the areas of the API that the access profile covers, with the scopes the API calls of each declare. Static: the same list for every session. A caller that keeps its own table of what needs what (for example a command line that says which commands a login cannot run) checks it against this list.
the areas, in the order the profile lists them
Log out: end the user session of this instance at AM (POST .../sessions?_action=logout with the session token)
and remove the token cache entries that hold the credentials of that session, so that no other process picks up a
session that is gone. This is the explicit logout, for a caller who asks for it: it ends the session even when the
instance restored it from the token cache. The instance stops refreshing by itself afterwards (no timer, no refresh
handler) and holds no credentials; getTokens() logs in again when it is called.
An instance without a user session (a service account, a token that a caller presented) has nothing to end:
the answer is none and nothing changes. The access token of a login is not revoked: the Ping documentation
describes the token revocation endpoint for the clients that authenticate with a secret, but not for the public
clients that these logins use, so no revocation is attempted and the token ends by its own expiry.
what happened to the session. Throws if the logout request fails; the instance is then left as it was.
Anonymous deployment-type probe: identifies the deployment type of a
host WITHOUT any credentials or session — two POSTs to
/oauth2/authorize with the built-in admin client ids (no cookie, no
CSRF token) and elimination:
idmAdminClient (cloud built-in) answers 302 → cloudidm-admin-ui (ForgeOps built-in) answers 302 → forgeopsconclusive is false and deploymentType is
'classic' only for backward compatibilityA 302 means "client exists AND its registered redirect URI matches" —
the same clients with an unregistered redirect answer 400
redirect_uri_mismatch, and an unknown client answers 400
invalid_client. Verified live (2026-10-12) against a real AIC tenant
(302/400) and a real ForgeOps deployment (400/302). Classic is
inferred from two 400 answers and has not been verified live.
Intended for pre-auth flows: prompts and previews that want the deployment type (realm map, cloud-only gating, help text) before any login is possible — e.g. a host that appears on the command line or via an env variable with no saved connection profile.
Each request times out after 8 seconds. NOTE: reads nothing from state
except the connection settings that shape the HTTP calls (allow-insecure,
proxies, header overrides); never writes to it. Safe to call at any time.
the AM base URL to probe, e.g. https://cdk.iam.example.com/am
the detected deployment type, whether the evidence supports it (conclusive), plus the raw per-client responses (for callers that want to log or branch on the evidence)
Applies an already-obtained, externally-issued OAuth2 access token to
state, ready for immediate use. UnlikegetTokens()/getTokensInteractive(), this never talks to an authorization endpoint itself — the token was already minted (and, by the caller's own contract, already verified) elsewhere; this only wires it ontostateusing the exact same deployment-type-specific handling a real browser login uses. Intended for hosts that resolve their own caller identity per request (e.g. an MCP server acting as an OAuth2 resource server) rather than performing a login themselves.