---
title: "Rotate the API key"
description: "Replace the store's API key with a new one and return it. The old key stops working at once, including for the request that rotated it. The key is shown only in this response."
url: https://docs.invoicefalcon.com/v3-reference/account/rotate-the-api-key/
api: "API v3 reference"
method: POST
path: "/account/integrations/api_key/rotate"
---

# Rotate the API key

`POST https://app.invoicefalcon.com/api/v3/external/account/integrations/api_key/rotate`

Replace the store's API key with a new one and return it. The old key stops working at once, including for the request that rotated it. The key is shown only in this response.

**Note:** Every integration using the old key must be updated. Not offered to assistants. Send it first without `confirm`: nothing changes and the 409 `confirmation_required` says what would. Tell the merchant, ask, and resend with `confirm: true` (`?confirm=true` on a DELETE) only after they agree.

## Request body

- `confirm` (boolean): Send true only after the merchant agreed. Without it the key is kept and the 409 says what would happen.

## Returns

- `api_key` (object)
  - `configured` (boolean): e.g. `true`
  - `key` (string): e.g. `if_api_key_YOUR_KEY`
- `payment_processor` (object)
  - `connected` (boolean): e.g. `false`
  - `name` (string, nullable)
  - `stripe_checkout_v2` (boolean): e.g. `false`
- `customer_accounts` (object)
  - `translations` (array of anys)

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Example request

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/account/integrations/api_key/rotate" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true
  }'
```

## 200

The updated resource.

```json
{
  "api_key": {
    "configured": true,
    "key": "if_api_key_YOUR_KEY"
  },
  "payment_processor": {
    "connected": false,
    "name": null,
    "stripe_checkout_v2": false
  },
  "customer_accounts": {
    "translations": []
  }
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

