# Authentication

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

## 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`.

```
recala login
```

```
recala whoami --json
```

An agent uses the signed-in person’s role. [Write confirmation](https://recala.co/developers/agents/#guarded) 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.

```
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:

```
recala org show --json
```

```
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.

```
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](https://recala.co/developers/cli/keys/#cmd-keys-events) and revoke keys that are no longer used.