Using the API

API authentication

Create an API key, and send it as a bearer token on every call.

Every call to the API carries one credential, in one header:

text

authorization: Bearer <api-key>

For anything that is not a person at a keyboard — a CI job, a backend, a Terraform run — that credential is an API key. An API key begins pk_, needs no exchange and no refresh, and works until you revoke it or it expires.

Create a key

API keys → Create key → name it, choose what it may do → Create

The key is shown exactly once, in key_string on the response. Plany keeps only enough to recognise it, so a key you did not copy cannot be shown again — create another and delete the first.

Use it

export PLANY_API_KEY=pk_...
plany playpute servers list

Keep the key in an environment variable or your CI's secret store rather than in a file. A key written into a .tf file is a credential in version control.

Narrowing a key

A key acts as the identity it was created for, and can be narrowed further when you create it:

Field	Effect
`scopes`	Limit the key to these permission scopes, below what its identity holds.
`expire_time`	Stop the key working at this time.
`subject`	Act as a service account rather than as you.

The usual shape for automation is a service account with only the roles the job needs, and a key for that service account. See Access control.

Rotating and revoking

RotateApiKey returns a new key and keeps the old one working for a grace period, so you can redeploy without an outage. DeleteApiKey stops a key immediately. Every call a key made is in your activity log, filterable by the key.

Signing in as a person

People sign in through the console, or with plany auth login for the CLI, which keeps its own session and refreshes it for you. Your own programs should use an API key rather than a person's password.