Service accounts and API keys

This page shows you how to give scripts, CI pipelines, and other machines their own credentials — and how to manage the personal API keys attached to your own account.

The two kinds of credentials

• A service account is a machine identity that belongs to one project, like a robot member of the team. It gets an email-shaped name — `<name>@<project-short>.cai.local` — and holds a project role (member or admin) exactly like a person would. Its authority stops at its own project.
• An API key is a long-lived bearer credential with the shape `cai_<keyid>_<secret>`. A key can belong to a service account ("acts as the machine") or to you personally ("acts as you"). Only a hash of the secret is stored, so the platform itself cannot show it to you twice.

Session tokens from signing in expire after 12 hours; API keys are what you use for anything unattended. See API authentication for how all the credential types fit together.

Create a service account

You need the project admin role. Project members can see the list but not create.

1. Go to Security → Service accounts in your project and click Create.
2. Choose a name (a lowercase DNS-style label, like ci-deploy) and a display name.
3. Pick its role: member for most automation, admin only if it must do irreversible things.

Names are reserved permanently, even after deletion. If you try to reuse one:

that name is taken. Service account names are reserved permanently, including after deletion, so that a new principal can never inherit an old one's grants and audit history

Mint a key (the copy-once dialog)

On the service account's detail page, click Create key. You choose a display name and an expiry: 0 for a key that never expires, or 1 to 3650 days. Anything else is rejected with:

expires_in_days must be between 1 and 3650, or 0 for a key that does not expire

The console then shows the full secret in a dialog whose Close button stays disabled until you tick "I have copied it". The API says why:

copy this now - only a hash is stored, so it cannot be shown again. If it is lost, revoke this key and create another.

Copy it now

The secret appears exactly once. There is no recovery. Lose it, revoke it, mint a new one.

Use the key by exporting it for the CLI:

export CAI_TOKEN=cai_xxxx_yyyy
platformctl whoami

You should see:

ci-deploy@ab12cd.cai.local  role=user  (credential: $CAI_TOKEN)

The platform is in alpha and has no public API hostname yet — scripts reach the API through $CAI_API (an endpoint your administrator gives you) or the CLI's automatic port-forward. The CI/CD tutorial walks through a full pipeline setup.

Your personal keys

Security → My API keys (it lives above any project — keys belong to your account, not a project) works the same way: create with the copy-once dialog, list, revoke.

A personal key acts as you, re-resolved on every request. It never freezes your authority at minting time: if you gain a project, the key gains it; if you lose a grant or get demoted, the key loses it on its very next call. A key can never assert a role you no longer hold.

Revocation

Revoking any key takes effect immediately:

effective immediately - the next request presenting this key is refused

Deleting a service account revokes every key it held in the same transaction, and the name stays reserved:

every key it held was revoked in the same transaction; the name stays reserved

Changing a service account's role

Role changes happen on the IAM & members page, where service accounts appear alongside human members. You can change the role there, or remove just the grant — removing the grant leaves the account and its keys alive but powerless in that project.

What service-account keys can never do

A service-account credential cannot create or manage credentials, accounts, or membership — by design. If a leaked key could mint replacement keys, revoking it would achieve nothing. The API refuses with:

a service account cannot create or manage credentials. Sign in as a user (or use your own API key) to issue keys - otherwise a leaked key could mint replacements and revoking it would achieve nothing

Every create and revoke is written to the project's audit log (serviceaccount.create, serviceaccount.key.create, serviceaccount.key.revoke, apikey.create, apikey.revoke), so key lifecycle is always reconstructable.

Quick reference

Action	Where	Who
List service accounts	Security → Service accounts	Project member
Create service account / mint or revoke its keys	Security → Service accounts	Project admin (human or personal key — never a service-account key)
Delete service account	Its detail page	Project admin
Change its role / remove its grant	Project → IAM & members	Project object admin
Personal keys	Security → My API keys	You

Next steps

• CI/CD with a service account
• API authentication — every credential shape in one place
• Quotas and audit log — where key events are recorded