Authentication

There are three ways to be somebody on Plany:

• A user — a person, signing in with an email and password.
• An API key — for your own tooling, CI, a matchmaker or a fleet controller.
• A service account — a non-human identity that roles are granted to, which API keys and your workloads act as.

Signing in

The console signs you in in the browser. The CLI does it from a terminal:

1plany auth login                   # prompts for your email and password
2plany auth login --account acme    # when you belong to several accounts
3plany auth status
4plany auth logout

For a job with nobody at a keyboard, do not sign in: set PLANY_API_KEY to an API key. The CLI and the Terraform provider both read it.

Confirming your email

A new account is sent a confirmation link, and until it is followed the account can do nothing else — every call is refused. Open the link on any device; a session already signed in somewhere else picks the change up the next time it refreshes, so nobody has to sign in again.

plany auth verify-email --resend          # send another link (one a minute)
plany auth verify-email '<link from the email>'

The link works for a day, and only the newest one works.

Changing or resetting your password

Change it from Settings → Security in the console, or:

plany auth password change

If you have forgotten it, use Forgot your password? on the sign-in page, or:

plany auth password forgot --email you@example.com
plany auth password reset                 # paste the link from the email when asked

A reset link works once, for an hour, and asking again replaces it. The answer to asking is the same whether or not the address has an account, so the form cannot be used to find out who has one.

Either way, every other session is signed out, and the account's address is sent a notice that the password changed. A reset does not stand in for a second factor: with one enabled, a reset changes the password and you sign in with both.

Tokens

Whatever you hold — a password, an API key — is exchanged for a short-lived token with IssueToken, and that token is what every call carries:

authorization: Bearer <token>

A token lasts an hour unless you ask for less with requested_lifetime. Two more fields narrow it:

• scopes — limit the token below what the credential could otherwise do. Asking for a scope the credential does not have fails rather than silently giving you less.
• account — bind the token to one account, if you belong to several. Naming an account you hold no role on is refused.

An API key can also be sent directly as the bearer — every sample in this documentation does that with $PLANY_API_KEY.

Refresh tokens

A password sign-in returns a refresh token alongside the access token. Each refresh replaces it, and presenting one that has already been used ends the whole session: a refresh token used twice means somebody else has a copy of yours.

RevokeToken ends a session immediately. Given credential_name instead of a token — an API key's name, say — it revokes every unexpired token minted from that credential.

API keys

accounts/{account}/apiKeys/{api_key}

API keys → New key → choose who it acts as, its scopes and projects → Create key

Narrowing a key

Rotating and revoking

RotateApiKey returns a new key and leaves the old one working for a grace period — 24 hours unless you set grace_period — so a fleet can move to the new key without a coordinated deploy.

last_use_time shows when a key was last used, to the minute, so a key nothing has used in months is easy to find and revoke.

Service accounts

accounts/{account}/serviceAccounts/{service_account}

A service account is an identity for something that is not a person. Roles are granted to it exactly as they are to a user.

Team & access → Service accounts → New service account → Create

service_account_id is chosen when it is created and cannot be changed. Setting disabled makes it fail to authenticate while keeping its role grants, so access can be paused without losing the record of what it was given.

Workloads that act as one

A game server or a sandbox can act as a service account you own — which is how a fleet of servers shares one set of grants. Leave it out and Plany creates an identity for the workload and grants it exactly what it needs, such as reading the secrets you attach and pulling its image from your registry.

Passwords

ChangePassword replaces your password and needs the current one.

Sign-in alerts

Plany emails you when your account is signed in to from a device it has not seen before — not on every sign-in, so that the email which matters stands out.

Security emails cannot be turned off.