Passbolt API JWT flow shows why secrets still need layered identity controls

At a glance

What this is: This is a technical explainer of Passbolt’s JWT-based API authentication flow and its token lifecycle, with the key finding that secure API access still depends on careful handling of secrets and refresh tokens.

Why it matters: It matters because IAM and security teams often extend human-authentication assumptions into machine access, where API tokens, signing keys, and refresh paths need separate lifecycle governance.

👉 Read Passbolt's explanation of JWT authentication for API access

Context

API authentication for scripts and integrations is not the same as human login. Once a team moves credentials into code, the security model shifts to challenge handling, key protection, and token reuse, which are all identity governance problems even when the subject is a machine account or integration.

Passbolt’s JWT flow is a good example of how cryptographic authentication can still create governance exposure if the surrounding secret lifecycle is weak. The core issue is not whether the exchange is encrypted, but whether the private key, refresh token, and user identifier are controlled with the same discipline as any other non-human identity.

For teams managing secrets, service accounts, and API-driven automation, the operational question is straightforward: can you prove who is allowed to mint, store, and renew access outside the web UI, and can you revoke it cleanly when the integration changes?

Key questions

Q: How should security teams govern API authentication that uses signed challenges and refresh tokens?

A: Treat the flow as machine identity governance, not just authentication plumbing. Require named ownership, protected private key storage, separate review of refresh rights, and a revocation path for both the token and the key when the integration changes. If the API can renew access on its own, that renewal path must be governed like any other privileged entitlement.

Q: Why do refresh tokens create more risk than short-lived access tokens?

A: Refresh tokens extend the life of the identity beyond the original login, so a stolen or mismanaged refresh token can keep reissuing access without redoing the full authentication ceremony. That makes renewal rights a persistence mechanism. Security teams should classify refresh tokens as high-value secrets with their own lifecycle, storage, and revocation controls.

Q: What do teams get wrong about cryptographic API authentication?

A: They often assume that encryption and signing eliminate governance risk. In practice, the cryptography only proves message integrity and origin. It does not solve who owns the identity, where the private key lives, how long the refresh path remains valid, or how the integration is retired. Those are lifecycle and access-management questions, not protocol questions.

Q: How can organisations tell whether an API login flow is outside its intended boundary?

A: Look for refresh tokens or private keys stored in code, shared automation, personal devices, or undocumented scripts. If the identity can continue operating after the original use case ends, the flow has escaped its intended boundary. Governance should require a named owner, a revocation process, and a periodic review of where the renewal material is used.

Technical breakdown

JWT challenge-response for API access

Passbolt does not treat JWT as a simple username-and-password exchange. The client first creates a challenge payload with a version, domain, random verify token, and expiry, then encrypts and signs it before sending it to the server. That design binds the request to a specific instance and proves both confidentiality and authenticity. The server then decrypts the message, verifies the signature, and returns encrypted tokens. The important architectural point is that authentication is split across key ownership, challenge freshness, and response decryption rather than a single bearer token check.

Practical implication: protect the signing key and challenge generation path as production credentials, not developer convenience artifacts.

Why refresh tokens expand the identity control surface

The access token is only part of the picture. The refresh token extends the session and becomes the mechanism by which long-lived API access can persist beyond the original exchange. In identity terms, that means the system is no longer just proving initial identity, it is also governing session renewal. If refresh tokens are stored in scripts, CI jobs, or shared automation, the effective trust boundary widens well past the original login event. That is a classic machine-identity pattern: the point of compromise may be small, but the renewal path keeps the account viable.

Practical implication: inventory every place refresh tokens can be stored, and treat renewal rights as a separately governed entitlement.

OpenPGP as a trust wrapper around machine identity

The use of OpenPGP to encrypt and sign the challenge is doing two jobs. Encryption limits who can read the payload, while signing proves the request came from the owner of the private key linked to the user account. This is useful because API authentication often fails when teams assume transport security alone is enough. It is not. The cryptographic wrapper only works if key distribution, private key storage, and server-side verification are all controlled tightly. The authentication ceremony is therefore a machine-identity control pattern, not just a protocol trick.

Practical implication: align key management, secret storage, and account lifecycle review so the cryptographic flow is actually enforceable.

NHI Mgmt Group analysis

JWT authentication for APIs is still an identity governance problem, not just an implementation detail. The article shows a machine identity exchanging signed challenges and encrypted responses to obtain bearer tokens, which means the real control point is lifecycle governance around keys and tokens. Once an integration can renew access programmatically, the organisation is governing non-human access, not merely securing a login flow. Practitioners should treat this as machine identity with explicit entitlements, not developer authentication convenience.

Refresh tokens are the persistence layer that most teams under-model. The access token is visible and temporary, but the refresh token determines whether the identity can continue to operate after the first session. That creates the familiar NHI failure mode of standing privilege through renewal rights, even when the initial exchange is short-lived. The practical conclusion is that token renewal must be governed as its own entitlement and offboarding event.

OpenPGP-based authentication illustrates that cryptography does not remove lifecycle risk. Encryption and signing can verify origin and confidentiality, but they do not answer who approved the integration, who can reissue the private key, or who can retire it when the business use case ends. That is the governance gap: secure transport can coexist with weak identity lifecycle control. Teams should not confuse cryptographic ceremony with complete control.

Passbolt’s flow reinforces a named concept: token renewal debt. Token renewal debt is the accumulation of long-lived renewal paths, stored refresh material, and stale integration accounts that outlive the original business need. It is the machine-identity equivalent of access that remains valid because the renewal mechanism was never revisited. Practitioners should view any API that can refresh itself as a lifecycle object, not a one-time authentication event.

From our research:

• 28.65 million new hardcoded secrets were detected in public GitHub commits in 2025 alone, a 34% year-over-year increase and the largest single-year jump ever recorded, according to The State of Secrets Sprawl 2026.
• 64% of valid secrets leaked in 2022 are still valid and exploitable today, proving that detection without revocation leaves identity risk intact.
• For the broader lifecycle context, see Guide to the Secret Sprawl Challenge for how exposed secrets move from discovery to operational misuse.

What this signals

With 28.65 million new hardcoded secrets detected in public GitHub commits in 2025, the governance problem is no longer isolated to a few careless scripts. API authentication flows that depend on stored tokens, signing keys, or renewal material should be treated as high-volume identity assets, not implementation leftovers.

Token renewal debt: this is the point at which a short-lived login becomes a long-lived governance liability because the refresh path outlives the business need. Teams that already struggle with secret sprawl should expect the same pattern to appear in API auth, automation, and integration accounts.

If your programme already maps service accounts and secrets into lifecycle processes, the next step is to extend that discipline to every API login path that can reissue access. The relevant control question is not whether the flow works, but whether it can be retired cleanly when the integration changes.

For practitioners

• Separate initial authentication from renewal governance Track refresh tokens as distinct entitlements from access tokens, with explicit ownership, review, and revocation steps for each integration.
• Store private keys in controlled secret management paths Keep the user private key out of shared scripts, developer laptops, and ad hoc automation so the signing step remains tied to a governed identity.
• Bind API access to a named machine identity record Document which service, workflow, or operator owns the JWT flow, then review it during joiner-mover-leaver and offboarding processes.
• Revoke renewal paths when integrations change Treat user_id, refresh token handling, and key rotation as part of the same offboarding event when an automation is replaced or retired.

Key takeaways

• JWT-based API authentication still depends on disciplined machine identity governance, especially around keys and renewal rights.
• Refresh tokens create persistence risk because they extend access beyond the original authentication event.
• Cryptography improves assurance, but lifecycle controls decide whether the integration remains safe over time.

Key terms

• Refresh Token: A refresh token is a credential that allows an authenticated identity to obtain new access tokens without repeating the full login ceremony. In machine access flows, it becomes a persistence mechanism and must be governed as a separate secret with its own storage, rotation, and revocation lifecycle.
• Challenge-response Authentication: Challenge-response authentication proves identity by requiring the caller to respond to a server-issued challenge rather than sending reusable credentials directly. In API and machine identity contexts, it reduces replay risk, but only when the challenge, signing key, and response verification are all tightly controlled.
• Machine Identity Lifecycle: Machine identity lifecycle is the governance of how a non-human identity is created, approved, used, reviewed, rotated, and retired. It applies to API credentials, service accounts, tokens, and keys, and it is the control layer that determines whether authentication remains safe over time.

What's in the full article

Passbolt's full article covers the operational detail this post intentionally leaves for the source:

• Step-by-step GPG challenge creation and signing commands for API authentication workflows
• Exact request and response payload examples for the JWT login and refresh flow
• How to retrieve the server public key and user identifier in the Passbolt interface
• A working end-to-end example script for implementing the sequence in code

👉 Passbolt's full guide includes the challenge, signing, login, and token refresh steps in sequence.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity lifecycle are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are responsible for identity security strategy or NHI governance in your organisation, it is worth exploring.