Broker a short-lived cloud role

Intramedial is in restricted beta. At sign up or sign in, you have to provide the beta tester password you received or request one at preview@intramedial.com. Thank you.

Loading…

Use case

The job

Agents should hold no standing cloud keys. The broker checks the role against protected classes, requires a live lease on the exact role ARN held by the agent, then asks STS for a session. Issuance is ledgered with the actor, the role and the expiry, never the keys.

StatusThe secret key appears once, and cannot be recalled

The answer carries the secret access key and the session token once, and the ledger never holds them. Releasing the lease does not revoke a credential already issued: it lives until expirationMs. STS refuses sessions under 900 seconds.

Prerequisites

Before you start

Plan: Any plan the workspace has
Credential: A workspace API key
You also need: A role ARN that starts with arn:aws:iam::
An OIDC token for STS; AWS checks it, the broker does not

The code reads the key from INTRAMEDIAL_KEY. Keep it in your shell or your secret store, never in a file you commit. Calls that need a signed-in person cannot use a key: the console makes them.

Walkthrough

Steps

Lease the role ARN
Take a lease on the exact role ARN, as the agent that will use it. The credential's lifetime is capped by the lease's remaining time.

Sample output

What comes back

assumed is true; the lease and expiry follow.

JSON

200 OK

{
  "assumed": true,
  "roleArn": "arn:aws:iam::123456789012:role/deploy",
  "sessionName": "release-agent",
  "leaseId": "lease_4b7e",
  "leaseScoped": true,
  "expirationMs": ,
  : ,
  : ,
  : 
}

Evidence

What the record shows

It shows

A lease holder was issued a role session that ends at expirationMs.
Issuance was ledgered with the actor, role and expiry.

It does not show

Keep going

Next steps

Modules

iam.assumeiam-assume

coordination.leasecoordination-lease

Documentation

Cloud credential broker/docs/iam-assume

curl -sS -X POST https://api.intramedial.com/api/v1/acp/coordination/lease \
  -H "Authorization: Bearer $INTRAMEDIAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "arn:aws:iam::123456789012:role/deploy",
  "actorDid": "did:web:acme.example:agent:release"
}'

const res = await fetch("https://api.intramedial.com/api/v1/acp/coordination/lease", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTRAMEDIAL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resource: "arn:aws:iam::123456789012:role/deploy",
    actorDid: "did:web:acme.example:agent:release",
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.intramedial.com/api/v1/acp/coordination/lease",
    headers={"Authorization": "Bearer " + os.environ["INTRAMEDIAL_KEY"]},
    json={
        "resource": "arn:aws:iam::123456789012:role/deploy",
        "actorDid": "did:web:acme.example:agent:release",
    },
    timeout=30,
)
print(res.status_code, res.json())

Assume the role

Send the role, the agent, a session name and the web identity token. The answer carries the secret once, so save it where logs cannot see it.

curl -sS -X POST https://api.intramedial.com/api/v1/acp/iam/assume \
  -H "Authorization: Bearer $INTRAMEDIAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "roleArn": "arn:aws:iam::123456789012:role/deploy",
  "actorDid": "did:web:acme.example:agent:release",
  "sessionName": "release-agent",
  "webIdentityToken": "eyJ…"
}'
# Save the answer to assume.json: it holds the secret once, so keep it out of logs.

const res = await fetch("https://api.intramedial.com/api/v1/acp/iam/assume", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTRAMEDIAL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    roleArn: "arn:aws:iam::123456789012:role/deploy",
    actorDid: "did:web:acme.example:agent:release",
    sessionName: "release-agent",
    webIdentityToken: "eyJ…",
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.intramedial.com/api/v1/acp/iam/assume",
    headers={"Authorization": "Bearer " + os.environ["INTRAMEDIAL_KEY"]},
    json={
        "roleArn": "arn:aws:iam::123456789012:role/deploy",
        "actorDid": "did:web:acme.example:agent:release",
        "sessionName": "release-agent",
        "webIdentityToken": "eyJ…",
    },
    timeout=30,
)
print(res.status_code, res.json())

Use the keys for the job

Export the keys for the one job that needs them. They live until expirationMs, the expiry STS reports for the session.

Shell

export AWS_ACCESS_KEY_ID=$(jq -r .accessKeyId assume.json)
export AWS_SECRET_ACCESS_KEY=$(jq -r .secretAccessKey assume.json)
export AWS_SESSION_TOKEN=$(jq -r .sessionToken assume.json)
# jq -r .expirationMs assume.json   when STS says the credential ends

Release the lease at the end

Release the lease when the job ends. That stops the next credential from being issued. It does not recall the ones already issued, which live until expirationMs. To watch for bursts of requests, watchdog.check reads the iam.assume events.

curl -sS -X POST https://api.intramedial.com/api/v1/acp/coordination/release \
  -H "Authorization: Bearer $INTRAMEDIAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "arn:aws:iam::123456789012:role/deploy",
  "actorDid": "did:web:acme.example:agent:release"
}'

const res = await fetch("https://api.intramedial.com/api/v1/acp/coordination/release", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTRAMEDIAL_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resource: "arn:aws:iam::123456789012:role/deploy",
    actorDid: "did:web:acme.example:agent:release",
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.intramedial.com/api/v1/acp/coordination/release",
    headers={"Authorization": "Bearer " + os.environ["INTRAMEDIAL_KEY"]},
    json={
        "resource": "arn:aws:iam::123456789012:role/deploy",
        "actorDid": "did:web:acme.example:agent:release",
    },
    timeout=30,
)
print(res.status_code, res.json())

Agents act when the plane says yes, and the record says why.

The job

Before you start

Steps

Lease the role ARN

What comes back

What the record shows

It shows

It does not show

Next steps

Modules

Documentation

Trademarks Notice

Region

Choose your language

Assume the role

Use the keys for the job

Release the lease at the end

Related recipes

Take a lease and release it again

Check the ledger for silence

Gate a SaaS connector write

New recipes by email

Try the real kernel, no key.

Broker a short-lived cloud role

Agents act when the plane says yes, and the record says why.

The job

Before you start

Steps

Lease the role ARN

What comes back

What the record shows

✓It shows

×It does not show

Next steps

Modules

Documentation

Assume the role

Use the keys for the job

Release the lease at the end

Related recipes

Take a lease and release it again

Check the ledger for silence

Gate a SaaS connector write

New recipes by email

Try the real kernel, no key.

It shows

It does not show