# idpc auth

Manage stored credentials at `~/.config/ideal-postcodes/credentials.json` (or `%APPDATA%\ideal-postcodes\credentials.json` on Windows, or `$XDG_CONFIG_HOME/ideal-postcodes/...` if set). The file is written with mode `0600`.

<!-- -->

## `idpc auth login`[​](#idpc-auth-login "Direct link to idpc-auth-login")

Store an `api_key` (required) and `user_token` (optional) for later reuse. The api\_key is verified against `GET /keys/{key}` before being written.

| Flag               | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `--api-key <k>`    | **Required** in non-interactive mode; prompted interactively. |
| `--user-token <t>` | Optional. Unlocks `/keys/*` reads when present.               |

Non-interactive (no TTY or `--json`): `--api-key` is required; missing it returns `invalid_input`. `--user-token` is optional and stored only if supplied.

Interactive: prompts for the api\_key (required) then the user\_token (press enter to skip). Both inputs are masked.

### Output[​](#output "Direct link to Output")

```
{

  "success": true,

  "config_path": "/home/you/.config/ideal-postcodes/credentials.json",

  "available": true

}
```

### Error codes[​](#error-codes "Direct link to Error codes")

* `invalid_input` — non-interactive mode missing `--api-key`
* `auth_failed` — API rejected the supplied credentials during verification
* `write_failed` — unable to write credentials file

## `idpc auth logout`[​](#idpc-auth-logout "Direct link to idpc-auth-logout")

Remove the credentials file.

### Output[​](#output-1 "Direct link to Output")

```
{ "success": true, "removed": true, "config_path": "..." }
```

`removed: false` means there was no file to remove — not an error.

## `idpc auth whoami`[​](#idpc-auth-whoami "Direct link to idpc-auth-whoami")

Show where each credential was resolved from and call `GET /keys/{key}` to verify the api\_key is live.

### Output[​](#output-2 "Direct link to Output")

```
{

  "api_key": { "source": "env", "preview": "ak_mpl…" },

  "user_token": { "source": "config", "preview": "uk_jc6…" },

  "live": true,

  "available": true

}
```

`source` is `flag`, `env`, or `config`. `preview` is the first 6 characters of the credential followed by `…`.

Either credential may be `null` if it isn't configured. When `api_key` is `null` the API check is skipped — output omits `available` and reports `"live": false`.