invokationAn auth endpoint can be managed without pretending it is OAuth
A common custom API pattern is straightforward: an approved authentication endpoint accepts authorized credentials and returns a short-lived token. Subsequent requests attach that token in a documented header. When it is no longer usable, a client acquires another token or follows a documented renewal mechanism.
An integration layer can manage that lifecycle behind a connection profile. The application keeps invoking its operation instead of implementing a token-fetch loop in every service. The profile still needs the API’s actual contract. JWT is a token format, not evidence that the API implements OAuth or supplies a refresh token.
Everything below uses a fictional example.com service, redacted fixtures, and explanatory configuration. It is not a working authentication proxy and contains no credential values.
Write down the authentication contract first
Ask the API owner for the approved endpoint, HTTP method, request shape, credential type, token response field, lifetime source, required header, audience, scopes, and renewal behavior. Establish network approval and certificate requirements separately. “It returns a JWT” leaves most of those questions unanswered.
Suppose the fictional contract specifies POST https://auth.example.com/session/token, a credential reference resolved server-side, and this response:
{
"access_token": "[REDACTED]",
"expires_in": 120,
"token_type": "Bearer"
}
The 120-second lifetime is a fixture choice, not a recommendation. The fictional API documents expires_in as seconds measured from acquisition. Another API might return an absolute expiry, a documented session lifetime, or an appropriate token claim. If the lifetime contract is unknown, do not manufacture a reliable cache expiry from guesswork.
Keep configuration next to the connection
An illustrative profile fragment can describe the lifecycle without embedding secrets:
{
"profile": "custom-api.production",
"credentialRef": "secrets/custom-api/production@v3",
"auth": {
"method": "POST",
"endpoint": "https://auth.example.com/session/token",
"requestMapping": "approved-client-assertion@v1",
"tokenField": "access_token",
"expiresInField": "expires_in",
"expiresInUnit": "seconds",
"header": "Authorization",
"scheme": "Bearer",
"renewal": "reacquire",
"expiryBufferSeconds": 60,
"maxAcquisitionAttempts": 2
},
"allowedDestinations": ["https://api.example.com"]
}
This is proposed configuration, not a universal standard or an implemented Invokation API. Credential references are names, not usable values. A request mapping identifies reviewed adapter logic; it should not become an arbitrary script that receives every secret in the project.
Restrict endpoints, methods, redirects, audiences, and permissions. A caller-supplied destination URL must not receive the connection’s authorization header. Auth responses themselves can contain sensitive fields beyond the token; redact by an explicit safe policy before inspection or storage.
Understand what decoding a JWT establishes
The JWT specification defines claims such as exp and a token representation; it does not require every custom token contract to provide a refresh flow. Reading an unverified payload is not signature verification, identity authentication, or authorization. A decoded expiry can only be a conservative cache hint under an appropriate contract.
If your component is responsible for accepting JWTs as proof, it needs a separate validation design for trusted issuers, permitted algorithms, keys, audience, time claims, and application policy. That is a different responsibility from carrying an issued token to the API that validates it. Do not conflate a convenient parser with either role.
Some tokens are opaque. Do not reject a documented opaque token merely because it lacks JWT segments. The connection should follow the provider contract instead of inferring a protocol from token appearance.
Reuse tokens within a precise scope
Cache usable tokens per connection, environment, credential version, audience, and permissions. Never share a token across unrelated customers because both use the same hostname. Apply a buffer large enough for the expected request duration and reasonable clock uncertainty, without silently extending the provider’s expiry.
For the fixture above, the simulation marks renewal due after 90 seconds with a 60-second buffer. Three waiting requests should share one coordinated acquisition. A single-process promise is insufficient when several workers can renew concurrently; use an explicit coordination boundary and atomic publication of the resulting version.
If a token acquisition succeeds but the response is lost, determine whether reacquisition invalidates the previous token or creates a new session. That behavior belongs to the API contract. Blind concurrency can create repeated invalidation or exhaust authentication quotas.
Classify failures before renewing again
Invalid credentials generally require owner action or replacement. Insufficient permission requires a grant or configuration change. A temporarily unavailable auth endpoint may justify bounded backoff. An expired token can justify reacquisition only through the documented mechanism. A custom session may need an explicit reconnect state if unattended renewal is impossible.
Set a small acquisition-attempt budget, a total wait limit, and a connection-level suppression policy. Expose redacted categories and safe timestamps. Do not record passwords, assertions, authorization headers, tokens, or complete auth responses in ordinary logs. Monitoring should help an operator act without revealing the credential.
A supported session-based API mechanism can be handled similarly when documented. This is not permission to automate browser logins, bypass MFA, or defeat provider controls.
Keep renewal separate from business recovery
A request rejected before execution may be eligible to run after renewal. An ambiguous timeout on a write is different: the destination might have committed the action. Do not renew a token and automatically repeat an unknown payment or another non-idempotent side effect. Reconcile state or use the destination’s documented deduplication semantics.
The OAuth guide explains where delegated refresh and client-credentials reissuance differ. The recovery guide covers business-action safety independently of authentication.
Review checklist and next step
Confirm approved auth and destination endpoints, credential ownership, response mapping, lifetime units, cache scope, expiry buffer, concurrency coordination, bounded failures, and reconnect ownership. Test missing expiry, revoked credentials, unavailable auth service, simultaneous callers, and a lost acquisition response using synthetic fixtures.
Explore the managed authentication simulation for the proposed connection experience and the developer preview for an application call that never fetches a downstream token. If discussing this pattern through early-access research, describe categories only. Never submit real credentials, tokens, or private auth URLs.