# Rotate API keys

Rotating your API keys means changing which API key your organization uses to make authorized requests. 

As a best practice, we recommend rotating your API keys on a regular cadence that makes sense for your organization (e.g., every six months). Or you may need to rotate keys in response to a leaked key. 

## Prerequisites

- A user must be assigned to an <u>**engineer role**</u> to create or authenticate API keys. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles).
- (_For OAuth API keys: Option 1_) Have your new JWK entry ready to enter into the Redox dashboard. 

## OAuth API keys

You can rotate OAuth API keys without downtime or Redoxer involvement. You have two options for rotating an OAuth API key: 

1. (_Recommended_) Use one OAuth key with multiple public keys. 
2. Use multiple OAuth keys with unique public keys for each one. 

|  | **Option 1: One OAuth API key** | **Option 2: Multiple OAuth API keys** |
| --- | --- | --- |
| Recommended | Yes (follows best practices for rotating API keys) | No |
| Downtime | None | None |
| Requires third-party tool for public keys | Yes | No |
| Change client ID | No (client ID stays the same) | Yes (client ID must be updated) |
| Complexity | Medium (requires JSON editing) | Low |
| Risk | Medium (if there's a typo in JSON) | Low |

<details>
<summary>Option 1: One OAuth API key, multiple public keys</summary>

With this method, you can have a single OAuth API key with multiple public keys associated with it.

1. Log in to the Redox dashboard.
2. From the navigation menu, select the **Developer** page.
3. By default, the <u>Sources</u> tab opens. Click the **Authentication** tab to view the configured API keys and auth credentials. 
4. In the table, find the API key you want to rotate and click anywhere in its **row**. 
5. The **Details** page opens. Under the <u>Key pairs</u> section, click the **Edit** button. 
6. From the <u>Method</u> drop-down, click the **Provide your own public key** option.
7. Two tabs display. Click the **Edit JWKS entry** tab. 
8. Add the **new JWK** to the `keys` array without deleting the old one yet.


![The JWKS entry is editable after a user clicks the Edit button.](https://images.ctfassets.net/cl3wt5ehhnlv/2RTreUVsveJqkPWs7oF9Ax/45dc4e41daeea8b439da23eeba1adbb4/oauth-api-key-edit-jwks-entry.png)

*OAuth API key: Edit your JWKS entry*


9. The `keys` array now has two objects, the old JWK and the new JWK (like in the code example below). Click the **Save** button.


**Example: Two entries in keys array**

```json
{
  "keys": [
    {
      "kid": "old-key-id",
      "kty": "RSA",
      ...
    },
    {
      "kid": "new-key-id",
      "kty": "RSA",
      ...
    }
  ]
}

```


10. Update your system to use the new JWK. That means you must update the **private key** and the **key ID** (i.e., `kid`). _Don’t update the client ID_.
11. Once your system is updated, return to the API key settings in the Redox dashboard. Delete the **old JWK** from the `keys` array. Keep the new one.
12. Click the **Save** button.

</details>

<details>
<summary>Option 2: Multiple OAuth API keys</summary>

With this method, you can use multiple OAuth API keys with unique public keys associated with each one.

1. [Follow the steps for creating a new OAuth API key](https://docs.redoxengine.com/permalink/0CKpMIghEgSam9nJuzyXe/#provide-your-public-key-to-redox).
2. Once you have a new OAuth API key, update your system to use the new JWK. That means you must update the **private key**, **key ID** (i.e., `kid`), and **client ID** values.
3. Once your system is updated, return to the API key settings in the Redox dashboard. Delete the **old OAuth API key**. [Follow the steps for deleting an API key](/how-to-use-redox/manage-your-redox-setup/rename-or-delete-an-oauth-api-key), if you need to.

</details>

## Legacy API keys

Rotating legacy API keys requires downtime and usually involves Redox support. [Submit a request to our Help Center](https://redoxengine.zendesk.com/hc/en-us) if you need help with this.

Alternatively, you could start using OAuth API key(s) alongside—or instead of—legacy API key(s). To do this, [migrate from a legacy API key to an OAuth API key](/how-to-use-redox/manage-your-redox-setup/migrate-from-a-legacy-api-key-to-an-oauth-api-key).

> **Authentication how-tos**
>
> Learn how to authenticate API keys: 
>
> - [OAuth API key](/api-reference/redox-data-model-api/authenticate-an-oauth-api-key) (recommended method) 
> - [legacy API key](/how-to-use-redox/manage-your-redox-setup/authenticate-a-legacy-api-key)