# Your key

> A personal pmo key signs AI sessions and scripts in to PMO; this page covers getting one, where it lives, and what to do when it stops working.

Source: https://docs.crossbot.io/pmo/cli/keys
Product: pmo · Kind: how-to · Status: live · Last verified: 2026-10-20

A key is a long secret code, starting `pmo_`, that tells the PMO server who you are on every command. Most people no longer need one: [signing in](/pmo/cli/sign-in) with your Cross account is the first way in for a person. A key is for AI sessions, scripts and scheduled jobs, or for anyone who prefers one.

<Callout type="warn" title="Treat the key like a password">
  Anyone holding your key acts as you. Never paste it into Slack, an email thread, a ticket, a shared document, a commit or a PMO record. If it might have been seen by anyone else, ask the PMO owner to switch it off. That costs you only a new key.
</Callout>

## What a key decides

The server works out whose key it is, then does only what that person may do and records every change under their name.

|  | Who you are | What you see | What you may change |
| --- | --- | --- | --- |
| Comes from | The person the key was issued for | The engagements you have been given | Your role, limited by what each engagement grants you |
| Shows up as | Your name on every change, in every record's history | Records outside your access read as "not found" | A refusal that names the rule and who can do it instead |

Commands accept an "acting as" name. With a key, naming yourself is fine, leaving it out is fine, and naming anybody else is refused.

**One key per person or AI session, per computer.** Each key is labelled with the computer or session it is for, so a lost laptop's key can be switched off without touching any other. An AI session should have a key of its own, issued for it and for the person who runs it, so every change it makes records both.

**Shown once.** The server stores only a one-way fingerprint of your key, never the key, so nobody (the owner included) can look it up later. A lost key is replaced, not recovered. Keys do not expire; they stay valid until switched off.

**The board is separate.** Signing in to the PMO board in a browser uses your email and a password. A key is only for `pmo` and other programs.

## Get a key and put it in

<Steps>
<Step>

### Ask the PMO owner

Tell them which computer or AI session it is for, for example "work laptop". Your work email must be on PMO's team list first; if you have used the board, it already is. `pmo` cannot issue a key from your computer.

</Step>
<Step>

### Receive it privately

It arrives as one long line starting `pmo_`. Copy all of it. It will not be shown again.

</Step>
<Step>

### Put it in your settings file

If you are installing now, paste it when the install asks. If `pmo` is already installed, open your settings file and paste the key straight after `PMO_KEY=`, with no space. Save the file.

<Tabs items={['Windows', 'macOS', 'Linux']}>
  <Tab value="Windows">

```powershell
notepad "$env:APPDATA\pmo\config"
```

  </Tab>
  <Tab value="macOS">

```sh
open -e ~/.config/pmo/config
```

  </Tab>
  <Tab value="Linux">

```sh
nano ~/.config/pmo/config
```

  </Tab>
</Tabs>

</Step>
<Step>

### Check it

In a new terminal window, run `pmo whoami`. It should print your PMO id and your name, for example `person:you  (Your Name)`.

</Step>
<Step>

### Delete the message it came in

Once it works, remove the key from wherever it reached you. The copy in your settings file is the only one you need.

</Step>
</Steps>

## Where the settings file lives

| Computer | Settings file |
| --- | --- |
| Windows | `%APPDATA%\pmo\config` |
| Mac and Linux | `~/.config/pmo/config` (or under `XDG_CONFIG_HOME` when that is set) |

`PMO_CONFIG` names a different file. Only two lines are read, the server address and the key; any other line is ignored:

```sh
PMO_API_URL=https://pmo.crossbot.io
PMO_KEY=pmo_…your key…
```

- **A key wins.** When the `PMO_KEY` line holds a key, `pmo` sends the key and ignores any Cross account sign-in on this computer. An empty line means no key.
- **The window wins over the file.** A `PMO_KEY` set in the terminal window itself overrides the file. Set but empty in the window, it hides the file's key, so the sign-in is used.
- **A key's shape is checked first.** A key is `pmo_`, sixteen characters, an underscore, then the secret. One that is not shaped like that stops the command before anything is sent; it does not fall back to your sign-in.
- **Mistyped names are ignored.** Nothing checks the file when you save it. A misspelled setting name is treated as missing.
- **Reinstalling keeps the old key.** The install does not rewrite an existing settings file, so a new key goes in by editing it.
- **Protection.** On a Mac or Linux the install makes the file readable by you alone. On Windows it relies on your user folder's normal protection, so an administrator of the computer can read the key.

## When the key stops working

A problem with a key is never fixed by trying harder: either the copy is wrong, or you need a new key.

| What you see | Why | What to do |
| --- | --- | --- |
| PMO_KEY does not hold a key … a half-copied one is the usual cause | The line in your settings file is not the whole key, or has something extra around it. | Paste it again in full. Nothing was sent. |
| … PMO_KEY is not set | The key line is empty, or the settings file is not where `pmo` looks, and this computer is not signed in with a Cross account either. | Put the key in, or [sign in](/pmo/cli/sign-in) instead. |
| no identity: the key presented is not a live key on this machine | The server does not recognise it: it was switched off, or never issued there. | Ask the PMO owner for a new one. |
| you are …, and --as … names somebody else | A command named someone else as the one acting. | Leave the name out, or use your own. |
| pmo names somebody other than you | A key on the `PMO_KEY` line belongs to someone or something else. | Empty the line to use your own sign-in, or put in your own key. |
| You lost the computer, or posted the key somewhere | | Tell the PMO owner at once. They switch off that key; your other keys keep working. |

<Callout title="A refused key never falls back to nobody">
  A key that is present and does not check out is refused outright. `pmo` never quietly carries on as an anonymous user, so a switched-off key cannot keep working without anyone noticing.
</Callout>