# idpc keys

Inspect and manage API keys.

Every subcommand accepts `[key]` as an optional first positional. If omitted, the resolved api\_key is used — so `idpc keys details` and `idpc keys details ak_xxx` behave the same when your own key is configured.

All subcommands except `keys get` **require a user\_token**. The CLI preflights this before any HTTP call: if no user\_token is found via `--user-token`, `IDPC_USER_TOKEN`, or `idpc auth login`, the command exits with `code: missing_user_token` and a hint pointing to those three sources.

## `idpc keys get [key]`[​](#idpc-keys-get-key "Direct link to idpc-keys-get-key")

Public availability info — `GET /keys/{key}`. No user\_token is attached (the response shape changes if one is present, so the CLI explicitly omits it even when available).

## `idpc keys details [key]`[​](#idpc-keys-details-key "Direct link to idpc-keys-details-key")

Private key details — `GET /keys/{key}/details`. **Requires user\_token.**

## `idpc keys update [key]`[​](#idpc-keys-update-key "Direct link to idpc-keys-update-key")

Update key details — `PUT /keys/{key}/details`. **Requires user\_token.**

| Flag                 | Description                                      |
| -------------------- | ------------------------------------------------ |
| `--json-body <json>` | **Required.** Raw JSON body of fields to update. |

```
idpc keys update --json-body '{"notifications":{"email":"ops@example.com"}}'
```

## `idpc keys usage [key]`[​](#idpc-keys-usage-key "Direct link to idpc-keys-usage-key")

Lookup counts over a date range — `GET /keys/{key}/usage`. **Requires user\_token.**

| Flag              | Description                    |
| ----------------- | ------------------------------ |
| `--start <date>`  | Start date (YYYY-MM-DD or ISO) |
| `--end <date>`    | End date                       |
| `--tags <csv>`    | Comma-separated tag filter     |
| `--licensee <id>` | Filter by licensee id          |

## `idpc keys logs [key]`[​](#idpc-keys-logs-key "Direct link to idpc-keys-logs-key")

Paid lookup logs — `GET /keys/{key}/lookups`. Emits **raw CSV to stdout**. **Requires user\_token.**

| Flag              | Description           |
| ----------------- | --------------------- |
| `--start <date>`  | Start date            |
| `--end <date>`    | End date              |
| `--licensee <id>` | Filter by licensee id |

This command is CSV-only and does not support `--json` / `-q` — passing either errors with `invalid_input`. Redirect to a file or pipe into CSV tooling:

```
idpc keys logs --start 2026-01-01 --end 2026-01-31 > lookups.csv
```

## `idpc keys configs`[​](#idpc-keys-configs "Direct link to idpc-keys-configs")

All subcommands **require user\_token** (including `get` and `list`).

A config's `payload` is an opaque serialised-JSON **string** (matching the API's `ConfigNewParam` / `ConfigUpdateParam`). The CLI validates that it parses as JSON but does not interpret its contents.

### `list [key]`[​](#list-key "Direct link to list-key")

`GET /keys/{key}/configs` — list all configs.

### `get <config> [key]`[​](#get-config-key "Direct link to get-config-key")

`GET /keys/{key}/configs/{config}` — retrieve one.

### `create <name> [key]`[​](#create-name-key "Direct link to create-name-key")

`POST /keys/{key}/configs` — create a new config.

| Flag               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `--payload <json>` | **Required.** Serialised config payload (JSON string). |

```
idpc keys configs create my-site --payload '{"allowedUrls":["https://example.com"]}'
```

### `update <config> [key]`[​](#update-config-key "Direct link to update-config-key")

`POST /keys/{key}/configs/{config}` — update in place.

| Flag               | Description                                                                           |
| ------------------ | ------------------------------------------------------------------------------------- |
| `--payload <json>` | **Required.** Serialised config payload (JSON string). Replaces the existing payload. |

### `delete <config> [key]`[​](#delete-config-key "Direct link to delete-config-key")

`DELETE /keys/{key}/configs/{config}`. Requires `--yes` in non-TTY (or `--json`).

| Flag        | Description       |
| ----------- | ----------------- |
| `-y, --yes` | Skip confirmation |