# Create a key

> Requests a key and shows it once. Needs a payday.direct account signed in with X, sent as JSON, with purpose saying what the key is for. The key answers key_pending until Payday approves it; launch: true asks for launching, granted at approval.


`POST https://payday.direct/api/v1/keys`

Requests a key and shows it once. Needs a payday.direct account signed in with X, sent as JSON, with `purpose` saying what the key is for. The key answers `key_pending` until Payday approves it; `launch: true` asks for launching, granted at approval.

## Body

- `label` (string): A name for the key
- `purpose` (string, required): What the key is for. Payday reads it before approving the key.
- `launch` (boolean): Ask for a key that can launch coins. Granted, or not, at approval.

```json
{
  "label": "My terminal",
  "purpose": "Show fee recipients in my terminal",
  "launch": false
}
```

## Responses

- 201: Requested: the key is shown once and waits for approval (status pending)
- 400: purpose_required, purpose_too_long or too_many_keys
- 401: Not signed in
- 403: x_required: the account is not signed in with X
- 415: Not sent as JSON
- 429: Too many new keys

```json
{
  "id": "pd_aB3dE9xQ",
  "key": "pd_aB3dE9xQ...SHOWN_ONCE",
  "label": "My terminal",
  "purpose": "Show fee recipients in my terminal",
  "status": "pending",
  "limit_per_minute": 600,
  "can_launch": false,
  "launch_requested": false,
  "signed_in": true,
  "note": "Copy this key now. It is shown only once. It works once Payday approves it."
}
```

## Example

```bash
curl -X POST "https://payday.direct/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"label":"My terminal","purpose":"Show fee recipients in my terminal","launch":false}'
```