Skip to main content
POST
Assume role with web identity
Requires no IAM action. Access is decided by the endpoint’s own rules rather than by a policy — see the description above.

Body

application/json

Exchange a signed OIDC token for credentials in the account identified by the full role CRN.

web_identity_token
string
required

Signed OIDC JWT. The issuer must be registered in the role account; signature, expiry and an allowed audience are verified before evaluating role trust.

Example:

"eyJhbGciOiJSUzI1NiIsImtpZCI6..."

role
string
required

Full account-scoped role CRN. Bare UUIDs and names are not accepted.

Example:

"crn:iam::production:role/github-deployer"

session_name
string

A label recorded on the session and in the audit trail. Defaults to the token's sub claim, so an unnamed session still records which identity it came from.

Example:

"reports-exporter"

duration_seconds
integer
default:3600

Credential validity duration (15 min to 12 hours). A value above the role's own max_session_duration is rejected rather than clamped.

Required range: 900 <= x <= 43200
Example:

3600

Response

Role assumed successfully

A role session's credentials, in both forms it can be presented.

access_token is a bearer token for this API — send it as Authorization: Bearer <token>. The other four fields are AWS SigV4 credentials for the S3-compatible object storage endpoint, which speaks nothing else.

Both come from the same session and share its expiry, so revoking the session stops both at once. Use whichever the endpoint you are calling needs; there is no need to choose one at request time.

access_token
string

Bearer token for the Basaltic API. Present on every role session.

Example:

"eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9..."

token_type
string

Always Bearer when access_token is present.

Example:

"Bearer"

expires_in
integer

Seconds until access_token expires.

Example:

3600

access_key_id
string

SigV4 access key id, for the S3 endpoint.

Example:

"AKIA..."

secret_access_key
string

SigV4 secret, for the S3 endpoint.

Example:

"wJalrXUtnFEMI..."

session_token
string

SigV4 session token, for the S3 endpoint. Send as X-Amz-Security-Token and include it in SignedHeaders.

Example:

"FwoGZXIvYXdzE..."

expiration
string<date-time>

When the session — and therefore both credential forms — expires.

Example:

"2026-01-15T09:30:00Z"

account_id
string<uuid>

Owning account UUID of the target role.

account_handle
string

Owning account handle of the target role.

role_id
string<uuid>

Immutable UUID of the assumed role.