Skip to main content
Nuphos never stores long-lived AWS keys. To connect, you let it assume an IAM role in your account through OIDC web-identity federation, scoped to your team — each session gets temporary credentials that expire after about an hour. The agent can then inspect and operate your AWS resources: EKS, EC2, ECS, Lambda, S3, CloudWatch, IAM, and more.
Connecting an account requires the Administrator role on your team. See the IAM trust model for the security design behind this flow.

​
What you’ll set up

In your AWS account you create:
  1. An OpenID Connect identity provider that trusts Nuphos.
  2. An IAM role whose trust policy allows your Nuphos team to assume it.
  3. A permissions policy on that role (start read-only).
Then you paste the role’s ARN into Nuphos. There are two ways to do this. If you have the AWS CLI installed and signed in, Nuphos can do the whole thing for you. In Integrations → Connect → AWS, choose the guided path. Nuphos opens an agent session that runs the aws CLI on your machine and walks through creating the OIDC provider, the role, and its policies — pausing for you to approve every IAM change. When it’s done, it binds the role automatically.
The agent uses your local AWS CLI credentials; it never receives your keys. You approve each mutation before it runs.

​
Option B — Manual setup in the AWS console

Prefer to click through it yourself? Create everything in the IAM console, then paste the role ARN back into Nuphos.
1

Create the OIDC identity provider

In the IAM console go to Identity providers → Add provider and choose OpenID Connect:
  • Provider URL: https://nuphos.ai
  • Audience: sts.amazonaws.com
Click Add provider.
2

Create the IAM role with a web-identity trust policy

Create a role and set its trust policy to the following. Replace <your-account-id> with your 12-digit AWS account ID and <your-team-id> with your Nuphos team ID (copy it from Settings → Workspace → General):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<your-account-id>:oidc-provider/nuphos.ai"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "nuphos.ai:aud": "sts.amazonaws.com",
          "nuphos.ai:sub": "nuphos:team:<your-team-id>"
        }
      }
    }
  ]
}
Do not remove the nuphos.ai:sub condition. It pins the role to your team — without it, any Nuphos team could assume the role.
3

Attach a permissions policy

Start least-privilege and widen only as needed. A read-only baseline:
  • AmazonEC2ReadOnlyAccess
  • AmazonS3ReadOnlyAccess
  • (other service-specific …ReadOnlyAccess policies you need)
For dedicated, non-production accounts you may attach AdministratorAccess for convenience. Optionally attach IAMFullAccess if you want to let Nuphos adjust the role’s own policies later from the app.
4

Paste the role ARN into Nuphos

Copy the role ARN — it looks like arn:aws:iam::123456789012:role/NuphosRole — and paste it into the AWS binding dialog in Nuphos. Nuphos parses your account ID from the ARN.

​
Verification

When you submit the role ARN, Nuphos immediately tries to assume the role before saving the connection. If your trust policy is wrong, you’ll get a role_not_assumable error right away rather than a surprise later. IAM changes can take a few seconds to propagate, so Nuphos retries briefly.
If verification fails, double-check that the provider URL is exactly https://nuphos.ai, the audience is sts.amazonaws.com, and the sub value matches nuphos:team:<your-team-id> with your real team ID.

​
How credentials work

Value
Trust mechanismIAM role assumed via sts:AssumeRoleWithWebIdentity (OIDC)
Per-team isolationEnforced by the sub claim nuphos:team:<team-id>
Credential lifetime~1 hour per session, minted on demand
What’s storedOnly the role ARN — never your AWS keys
The agent only receives these credentials for a session when you’ve explicitly selected this account, and only if you pass the account’s member allow-list. See Access control.
Older connections may use a legacy static-connector trust instead of OIDC. OIDC web-identity federation is the recommended, per-team-isolated method and what new connections use.