Skip to main content
A Basaltic VM can obtain an identity JWT from its metadata service without storing a long-lived credential. Use it with AWS STS or another service that trusts Basaltic’s OIDC issuer. The VM needs an attached IAM role. Its policies must allow iam:GetWebIdentityToken on that role’s CRN. Restrict the audience to the destination service:
Apply this as an inline or attached role policy. Role boundaries also apply. basalt:IdentityTokenDurationSeconds contains the requested lifetime in seconds, including the default 300 when no duration is supplied.

​
Request a token inside the VM

First obtain an IMDSv2 session token. Then request an identity JWT with one external audience:
The JSON response has token and expires_at. Tokens default to 300 seconds; you can request 60–300 seconds. Repeated requests can return a still-valid cached token, so use the returned expiration. Every request checks current role permissions, including cache hits. This endpoint always requires IMDSv2, even if ordinary metadata permits IMDSv1. It accepts only audience and optional duration_seconds. The platform supplies the VM identity; a request cannot choose another VM, account, organization, or subject. The audience basaltic is reserved for API access and is rejected here. The three tokens involved are different:

​
Identity claims

The issuer is https://iam.basaltic.sh. JWTs use ES256 and include iss, sub, aud, iat, exp, and jti. The subject is:
Use the exact subject in the destination’s trust policy. These UUIDs are immutable. Renaming a resource does not change its identity, and recreating a VM with the same name produces a different subject. Two VMs sharing a Basaltic role still have different subjects. The destination must verify the signature against the issuer’s discovered JWKS before trusting these claims. Decoding a JWT without verifying it is useful for inspecting its contents, but proves nothing.

​
Maintain a token file

Guest-agent version 1.15.11-1 or later includes an identity-token command. Upgrade basaltic-guest-agent from your VM’s configured Basaltic package repository before using it. Run the helper as the same user as your application, with a private output directory. It refreshes the proof before expiration and atomically replaces a mode-0600 file:
The command stays running. Use --once for a single short task; that file is not refreshed. Continuous mode removes the file when stopped and removes an expired proof if refresh has failed. A second helper cannot own the same output file. For a service running as the existing app user, use a separate systemd unit:
/etc/systemd/system/basaltic-aws-identity.service
Configure the application to wait for the token file before its first AWS request. The helper refreshes identity proofs; the AWS SDK exchanges them and refreshes AWS credentials. See the AWS configuration.

​
Revocation and limits

Removing the role, changing its permissions, or revoking the underlying Basaltic role session blocks further issuance through that authorization. Existing identity JWTs remain usable until their expiration, at most five minutes. They are bearer proofs, not single-use tokens. Credentials already issued by an external service have that service’s own lifetime and revocation rules. A five-minute proof can produce a longer AWS session. To stop existing AWS access, use AWS session revocation controls too. All processes that can reach the VM metadata endpoint can request proofs under the attached role. A token file’s permissions limit local readers of that file; they do not isolate processes that can independently access metadata. Use separate VMs for workloads that require separate cloud identities. Detaching a role stops new metadata proofs. Existing Basaltic sessions can still call the token API until revoked or expired; revoke them too when removing access.