GET STARTED

Authentication

Use your own login in a terminal. Give CI a scoped organization key.

On this page

Sign in as a person

Run the command, open the printed browser link, type the one-time code and approve the request. The CLI saves a session and refreshes it when needed. On a remote machine, add --no-browser.

Terminal

recala login

Terminal

recala whoami --json

An agent uses the signed-in person’s role. Write confirmation is separate from signing in. recala logout ends this machine’s session.

Use an organization key in CI

API keys require organization-key access to be enabled on your Recala server. When it is disabled, key commands are unavailable; ask Recala support for access. The server setting ORG_API_KEYS_ENABLED defaults to off.

A person creates and manages keys with their own session. A key cannot create another key. The raw key is shown once; store it in your CI secret manager as RECALA_API_KEY, and set RECALA_ORG to the intended organization’s id.

Terminal

recala keys create --name "CI reports" --scope read --scope billing:read --credit-cap 0 --publish-cap 0

Run this in a person’s terminal with environment credentials cleared if they would override the saved session. Never paste a key into a command, log or agent prompt. In CI, after the secret manager injects the two environment variables:

Terminal

recala org show --json

Terminal

recala credits --json

Keys are bound to one organization. Choosing another organization does not extend access. Keys expire or can be revoked; they do not refresh like a saved session.

Credential and organization priority

Credential priority	Source
1	`RECALA_API_KEY`
2	`RECALA_TOKEN`
3	Saved login, including a token saved with `recala login --with-token`

A nonempty environment credential overrides the saved login. Running recala login does not remove that environment override. There is no --api-key flag.

Organization priority	Source
1	`--org` on the command
2	`RECALA_ORG` in the environment
3	The organization saved by `recala org use`

Names, slugs and ids are accepted. Use an explicit id in CI to avoid an ambiguous name.

Terminal

recala article list --org rebeam --json

Give the key only the scopes it needs

Scope	Allows
`read`	Read companies, topics, articles and reports.
`content:write`	Create content and manage the topic queue.
`content:edit`	Edit articles, manage revisions and review comments.
`publish`	Approve, schedule and unpublish for the allowed signing people. Owners only.
`billing:read`	Read credits and billing information.
`settings:write`	Change permitted company settings. Owners only.

A viewer can grant read and billing access; an editor can also grant content scopes; an owner can grant all six. A key remains bounded by its creator’s current role. Unlisted operations are refused. Payment, sign-in, key management, company creation and autopilot consent require a person’s session.

For a publish key, --sign-as must name the creator’s own email and --person names each active signer whose articles the key may approve and publish. These are explicit permissions, not permission to invent an author.

Expiry and caps

Key setting	Default	Accepted range
`--expires-days`	90 days	1–365
`--rate`	60 requests/minute	1–600
`--credit-cap`	5 articles/month	0–100
`--publish-cap`	3 articles/day	0–50

The organization’s plan and the key’s caps both apply. Article creation obtains a cost preview before spending. Setting a cap does not purchase credits. Read the key audit trail and revoke keys that are no longer used.