---
title: "Authentication"
description: "PW API Authentication"
url: "https://developers.perryweather.com/guides/perryweather-api/authentication"
image: "https://developers.perryweather.com/_og/d/c_Ocean.takumi,title_Authentication,description_PW+API+Authentication,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiIzAwODE5RSJ9fX0,p_Ii9ndWlkZXMvcGVycnl3ZWF0aGVyLWFwaS9hdXRoZW50aWNhdGlvbiI,s_Mk3yuf0hXke_02nK.png"
---

Perry Weather API

## Authentication

The Perry Weather API uses API keys to authenticate requests. Every call to the API must include a valid key in the `x-api-key` header so the server can identify your organization and enforce access controls.

## [Creating & Managing API Keys](#creating-managing-api-keys)

This section is for Perry Weather account admins who need to generate and manage API keys.

### [Prerequisites](#prerequisites)

You must have the access to edit integrations in your Perry Weather account to create keys. If you do not have this access, please contact your account admin.

### [Creating a key](#creating-a-key)

1.  In the Perry Weather dashboard, navigate to [**Integrations > Perry Weather APIs**](https://app.perryweather.com/Integrations/ApiManagement).
2.  Select the **API Keys** tab.
3.  Click **Create API Key**.
4.  Enter a descriptive name for the key (e.g. "Production API Key").
5.  Click **Create Key**.
6.  The key is displayed on screen. **Copy it immediately** — this is your only opportunity to view the key. You will not be able to retrieve it after closing the dialog.
7.  Click **Done**.

Warning

If you lose an API key, it cannot be recovered. You must delete the lost key and create a new one.

### [Viewing existing keys](#viewing-existing-keys)

The **API Keys** tab lists every active key for your organization. Each entry shows:

-   **Name** — the label you assigned when the key was created.
-   **Created** — the date the key was generated.

### [Deleting a key](#deleting-a-key)

1.  Locate the key you want to remove in the list.
2.  Click the **delete** icon on that row.
3.  Confirm the deletion in the dialog that appears.

Deletion is **permanent and immediate** — any application using the deleted key will lose access right away.

### [Replacing a lost key](#replacing-a-lost-key)

If a key has been lost or compromised, delete the old key and create a new one.

### [Key management best practices](#key-management-best-practices)

-   **Store keys securely.** Use environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault). Never hard-code keys in source files or commit them to version control.
-   **Rotate keys periodically.** Create a replacement key, update your applications, then delete the old one.
-   **Use descriptive names.** Name each key after its environment or application (e.g. "Staging - Weather Widget", "Production - Backend Service") so you can identify and manage them easily.
-   **Delete unused keys promptly.** Reducing the number of active keys limits your exposure if one is compromised.
-   **Limit key distribution.** Share keys only with the systems and team members that need them.

---

## [Using API Keys](#using-api-keys)

This section is for developers integrating with the Perry Weather API. Once an admin has provided you with an API key, include it in every request as shown below.

### [Authentication header](#authentication-header)

Add the `x-api-key` header to every HTTP request:

```text
x-api-key: YOUR-API-KEY
```

### [cURL](#curl)

```bash
curl -X GET "https://customer.api.perryweather.com/v1/health" \
  -H "x-api-key: YOUR_API_KEY"
```

### [JavaScript (fetch)](#javascript-fetch)

```javascript
const response = await fetch("https://customer.api.perryweather.com/v1/health", {
  headers: {
    "x-api-key": "YOUR_API_KEY",
  },
});
const data = await response.json();
```

### [Python (requests)](#python-requests)

```python
import requests

response = requests.get(
    "https://customer.api.perryweather.com/v1/health",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()
```