Installation Access Token

How installation access tokens work

An installation access token is issued to a specific installation, not to a person, and it carries only the permissions that installation has been granted. That makes it a practical way to let software act independently while keeping its authority narrow and time limited.

Because the token is tied to the installation context, it is usually used for machine-to-machine API calls rather than interactive sign-in. This matters when an app needs to read, write, or automate against a service without reusing a human user's session or password.

Why short-lived installation tokens reduce exposure

Short-lived tokens shrink the window in which a stolen credential remains useful. If the token is compromised, the attacker gets only the scope attached to that installation and only until expiry or revocation, which is safer than leaving a long-lived secret in code or configuration.

This pattern is especially valuable when the software instance is deployed broadly or runs unattended. A narrower token reduces the blast radius of a compromise, but it does not eliminate the need to protect the underlying app credentials used to obtain it.

For background on the broader identity model behind this pattern, see Ultimate Guide to NHIs.

Installation tokens in OAuth and API access

Installation access tokens sit in the wider OAuth-style pattern of delegated API access. They let a software client present a credential to a resource server and prove it is the authorised installation making the request, rather than a human user acting directly.

That is why audience restriction, scope control, and sender-bound token designs matter so much in practice. The token should be accepted only by the intended API and only for the intended actions, otherwise a stolen token can be replayed across systems or abused beyond its original purpose.

For the underlying protocol model, RFC 6749: The OAuth 2.0 Authorization Framework defines the core grant model, and RFC 9700: Best Current Practice for OAuth 2.0 Security reinforces modern protections against token theft and replay.

Operational lifecycle and governance

The practical security question is not just how the token is issued, but how it is governed over time. Teams need to know which installation received it, what scope it carries, when it expires, and how quickly it can be revoked if the app is removed, replaced, or suspected of abuse.

That lifecycle discipline becomes more important as installations multiply across repositories, tenants, or customer environments. If token ownership is unclear, organisations can end up with orphaned access, stale permissions, and a misleading sense of control over software that is still authorised to act.

For governance and lifecycle perspective, Guide to NHI Rotation Challenges explains why rotating and replacing non-human credentials is harder at scale, and Ultimate Guide to NHIs, Standards gives the wider control context.

How compromise is detected and contained

When an installation token is exposed, the first question is whether the token was used outside its expected pattern. Unusual API targets, unexpected geographies, abnormal request volume, or access after the installation should have been removed are all signals that the token may have been abused.

Containment usually depends on revoking the token, checking whether a fresh token was issued through the same app, and reviewing any downstream actions performed while the token was valid. If the token enabled write access, the post-incident review should include changes to repositories, configurations, workflows, or data copied through the API.

That detection-and-review discipline is illustrated by Sourcegraph breach 2023 and Internet Archive breach 2024, both of which show how exposed tokens can create persistence and follow-on access.

Risk and Threat Considerations

Installation access tokens are attractive targets because they often sit at the boundary between automation and real authority. If a token is stolen, an attacker may not need to break authentication again, they can simply use the token until it expires or is revoked.

Failure mechanism: Exposure through logs, code repositories, memory, misconfigured plugins, or compromised build and deployment paths can turn a scoped installation token into reusable API access.

Impact: The attacker can impersonate the installation, read or modify API data, trigger automation, and sometimes pivot into wider system or supply-chain compromise if the token had write capability.

Practitioner Guidance

Why practitioners should care: Treat installation tokens as disposable authority, not as static credentials. Their value comes from being narrow and ephemeral, so the surrounding issuance, storage, and revocation process has to be equally disciplined.

What to watch for: Watch for tokens that outlive the installation, are reused across environments, or are stored in places that many operators and tools can reach. Those patterns usually signal that the token is doing too much for too long.

Practitioner takeaway: The safest installation token is one that is tightly scoped, short lived, easy to revoke, and easy to trace back to the exact installation that received it.

Related resources from NHI Mgmt Group

• Should organisations prioritise token controls before expanding SaaS access?
• What is the difference between access token abuse and refresh token abuse?
• What is the difference between OAuth and token exchange for AI agent access?
• Should applications use one OAuth access token for multiple APIs?