Skip to content

Access Keys

Access Keys authenticate data-plane work (Object Storage, Message Queues, Secrets, Image Registry, SDK/CLI runtime) and programmatic management of the console API (Terraform / CI — Terraform).

They are not your console password. Create them once, store the secret safely, and use them in CI and servers. Requests signed with an Access Key do not prompt for MFA.

Create a key in the console

  1. Open IAM → Users → [user] → Access keys, or the account inventory IAM → Access Keys.
  2. Each user has one active key. If they already have one, use Rotate (this mints a new pair and immediately revokes every previous active key for that user).

  3. Copy once:

  4. Access Key ID — starts with HCAK…

  5. Secret access key — shown only on create/rotate

The table lists user, name, created, last used, status. It does not keep showing the HCAK id.

Permissions come from the user’s IAM (groups and policies), not from the key. Existing extra keys on old accounts keep working until that user rotates.

If you lose the secret, rotate (or revoke) the key. You cannot recover the secret later.

Configure the CLI

homecloud configure

Enter Access Key ID, secret, and apex domain when prompted. Credentials are stored under ~/.homecloud/credentials (multi-profile JSON).

export HOMECLOUD_ACCESS_KEY_ID=HCAK...
export HOMECLOUD_SECRET_ACCESS_KEY=...
export HOMECLOUD_APEX=holab.abrdns.com

Short forms HC_ACCESS_KEY_ID, HC_SECRET_ACCESS_KEY, HC_APEX also work.

homecloud --access-key-id HCAK... --secret-access-key '...' so ls media

homecloud configure import credentials.json

Use from the SDK

from homecloud import HomeCloud

client = HomeCloud(
    access_key="HCAK...",
    secret_key="...",
)
# or: HomeCloud.from_env()
# or: HomeCloud()  # reads ~/.homecloud/credentials

const { HomeCloud } = require("@homecloud-platform/sdk");

const client = new HomeCloud({
  accessKeyId: process.env.HC_ACCESS_KEY_ID,
  secretAccessKey: process.env.HC_SECRET_ACCESS_KEY,
  apex: process.env.HC_APEX,
});

Prefer scoped policies over * in production. Example: allow a deploy key to update one static website bucket only:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["so:ListBucket", "so:PutObject", "so:DeleteObject"],
      "Resource": [
        "arn:holab:so:::my-website",
        "arn:holab:so:::my-website/*"
      ]
    }
  ]
}

Attach policies via IAM → Policies / Roles. See IAM for roles, managed policy starters, and how Functions assume roles.

Console login vs Access Key

Task Use
Create a bucket or queue in the UI Console session
homecloud queues list / homecloud so ls-buckets homecloud login (JWT)
homecloud so cp / so sync / mq send Access Key
CI deploy of a static site Access Key in GitHub Actions secrets
Terraform provision of queues / buckets / secrets from CI User-bound Access Key, or GitHub OIDC (HC_ROLE_ARN) — Terraform
Day-to-day browsing in the browser Console session + MFA

You often use both: login for management listing, Access Key for transfers.

For Terraform in GitHub Actions, prefer OIDC over a long-lived HC_SECRET_ACCESS_KEY in GitHub Secrets. The provider exchanges a GitHub JWT at POST /api/v1/sts/assume-role-with-web-identity. See Terraform — GitHub OIDC.

Never commit secrets

Do not put Access Key secrets in git. Use your CI secret store (GitHub Actions secrets, etc.), or skip the long-lived secret entirely with GitHub OIDC for Terraform.

Troubleshooting

Symptom What to try
401 / unauthorized on so / mq Wrong key/secret, or key revoked; re-run homecloud configure
403 / permission denied Key policy too narrow; check IAM policies
Works in console but CLI fails Management call needs homecloud login; data-plane call needs Access Key
Old key after platform Redis flush Keys live in the database; cache rebuilds automatically. If a very old key predates encryption migration, revoke and recreate