## Generate a new API key

Generate a new API key for your merchant account. API keys are used to
authenticate your API requests and should be kept secure.

When you generate a new API key, you'll only see the full key once immediately
after creation. Make sure to store it securely at that time, as you won't be
able to retrieve it later. Give each key a unique, descriptive name to help
identify its purpose.

You can create multiple API keys to support different use cases. For example,
you might want separate keys for separate services. This also enables you to
rotate keys periodically for enhanced security.

Security best practices:

- Never share your API keys with others
- Don't commit keys to source control
- Rotate keys regularly
- Use different keys for different environments

If you suspect a key has been compromised, you can disable it immediately
through our API.

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/generate-key HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  name: string,
  permissions: array?,
}
```

Returns: object

## Request arguments

### `name` (string)

**Required**. A descriptive name for the API key to help you identify its purpose (e.g.
'Production API Key', 'iOS App Key', 'Backup Key').

### `permissions` (array)

_Optional_. Permission tokens granted to this API key (same string values as merchant roles).
If omitted, the key receives every permission (15 total).

Allowed values:

- `manage_contacts`
- `manage_developer_settings`
- `manage_disputes`
- `manage_payouts`
- `manage_settings`
- `manage_team`
- `manage_terminals`
- `manage_transactions`
- `view_contacts`
- `view_disputes`
- `view_payouts`
- `view_settings`
- `view_statements`
- `view_team`
- `view_transactions`

## Response attributes

### `key_id` (string)

**Always present**. The ID of the key. This can be used as an argument to `find-key`.

### `key` (string)

**Always present**. The secret key. It will only be shown once as a response to `generate-key`. Subsequent calls using `find-key` will display `MASKED` instead.

### `name` (string)

**Always present**. The name of the key that you provided when creating it.

### `revoked` (boolean)

**Always present**. Whether the key is revoked. If it is revoked, it cannot be used to make API requests.

### `created_at` (number)

**Always present**. The timestamp of the key creation as a Unix timestamp.

### `permissions` (array)

**Always present**. Permission tokens granted to this key.

Possible values:

- `manage_contacts`
- `manage_developer_settings`
- `manage_disputes`
- `manage_payouts`
- `manage_settings`
- `manage_team`
- `manage_terminals`
- `manage_transactions`
- `view_contacts`
- `view_disputes`
- `view_payouts`
- `view_settings`
- `view_statements`
- `view_team`
- `view_transactions`

## Errors specific to this endpoint

### `UNAUTHORIZED`

You must confirm your email before generating an API key. Please check your inbox for the confirmation email.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

This error occurs when the server encounters an unexpected internal error that
it cannot handle gracefully. This typically happens due to bugs, infrastructure
issues, or edge cases that weren't anticipated during development.

### `INVALID_ARGUMENTS`

This error occurs when the request contains invalid or missing parameters.
Common cases include missing required fields, or values that don't match the
expected format or type.

### `BAD_VERSION`

This error occurs when making requests to an API version that does not exist.
This commonly happens when using an outdated SDK or when the API version
specified in the request URL is incorrect.