Docs menu

Deploy and run

Cloud access without stored keys

Let an app use AWS, Google Cloud or Azure without pasting their keys into variables. The app asks CLI for a short-lived token, and your cloud swaps it for temporary access.

Explain it

When an app needs to use another cloud (files in an Amazon S3 bucket, a Google Cloud API, Azure storage), the usual way is to create a long-lived access key and paste it into the app's variables. Those keys are the kind that leak: copied into a chat, left in an old project, never changed in years.

CLI can do it without any stored key. With cloud access on, your app asks CLI for a short-lived signed note that says exactly which app it is, such as "the web app in production of project shop". You tell your cloud once to trust those notes for that one app, with only the permissions it needs. The app hands the note to the cloud and gets temporary access in return, lasting up to an hour. There's nothing to leak, rotate or forget.

How to do it: open an app, go to Settings, find Cloud access without stored keys and switch it on (owners and admins). Redeploy the app. Then pick your cloud: CLI shows the exact steps and the policy to paste, already filled in with this app's details.

"My app needs to read from an S3 bucket. Set it up without storing AWS keys."

CLI is an OpenID Connect issuer, like GitHub Actions is for workflows. Clouds that support workload identity federation (AWS, Google Cloud, Azure and most others, and HashiCorp Vault) can trust it.

Issuerhttps://api.clicloud.app/oidc
Discovery/oidc/.well-known/openid-configuration
Keys/oidc/jwks (RS256)

Turn it on

API
PUT /v1/services/:id/cloud-access
{"enabled": true, "audiences": ["sts.amazonaws.com"]}

Owners and admins only, since it lets the app act in your cloud. audiences is optional: when set, the app may only ask for those. On its next deploy the app gets:

Variable
CLI_OIDC_TOKEN_URLwhere to ask for a token
CLI_OIDC_REQUEST_TOKENproves which app is asking (sent as a bearer token)
CLI_OIDC_ISSUERthe issuer, for reference

{"enabled": false} stops the request token working at once.

Getting a token

Terminal
curl -s -H "Authorization: Bearer $CLI_OIDC_REQUEST_TOKEN" "$CLI_OIDC_TOKEN_URL?audience=sts.amazonaws.com"
JSON
{"token": "eyJ…", "expiresAt": 1767225600000}

ttl (seconds, 300 to 3600, default 900) sets how long it lasts. Each app can ask for 120 tokens a minute; cache one until shortly before it expires.

The token

JSON
{
  "iss": "https://api.clicloud.app/oidc",
  "sub": "project:prj_8f2k…:environment:production:service:web",
  "aud": "sts.amazonaws.com",
  "project_id": "prj_8f2k…",
  "environment": "production",
  "service_id": "svc_…",
  "service_name": "web",
  "deploy_id": "dep_…",
  "commit": "4f2c9e1…",
  "iat": 1767224700, "nbf": 1767224695, "exp": 1767225600, "jti": "…"
}

sub uses the project's id, not its name, so no other project can produce the same subject. Staging and other environments get their own subject (environment:staging). Trust the exact sub in your cloud, never a wildcard.

AWS

  1. IAM → Identity providers → Add provider → OpenID Connect. Provider URL https://api.clicloud.app/oidc, audience sts.amazonaws.com.
  2. Create a role for web identity with that provider, with only the permissions the app needs, and this trust policy (the dashboard fills it in):
JSON
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/api.clicloud.app/oidc"},
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {"StringEquals": {
      "api.clicloud.app/oidc:aud": "sts.amazonaws.com",
      "api.clicloud.app/oidc:sub": "project:prj_8f2k…:environment:production:service:web"
    }}
  }]
}
  1. Set AWS_ROLE_ARN on the app, and in code swap the token for credentials (fromWebToken in the AWS SDK for JavaScript, assume_role_with_web_identity in boto3). The dashboard shows both.

Google Cloud

Create a workload identity pool with an OIDC provider (issuer https://api.clicloud.app/oidc), map google.subject = assertion.sub, add the condition assertion.sub == "<the app's subject>", and let that principal use a service account. The dashboard gives a credential file of type external_account whose credential_source is CLI's token URL. Have the app write it at start with its request token, and set GOOGLE_APPLICATION_CREDENTIALS to it.

Azure

In your app registration, add a federated credential for Other issuer: issuer https://api.clicloud.app/oidc, subject the app's sub, audience api://AzureADTokenExchange. The app asks CLI for a token with that audience and uses it as the client assertion.

Keys

The signing key is kept encrypted with CLI's master key. Operators rotate it with POST /v1/admin/oidc/rotate; the old key stays in /oidc/jwks for a week, so tokens already issued still check.