Every Publer API request must include a valid API key. This guide shows you how to obtain, use, and manage your keys securely.

### Obtaining an API Key

1. Sign in to your Publer account (Business plan).
2. Navigate to **Settings → Access & Login → API Keys**.
3. Click **Create API Key**.
4. Enter a descriptive name for your key.
5. Select only the scopes your integration needs (e.g., `posts`, `media`, `accounts`).
6. Click **Create**.
7. **Copy** and **securely store** the key — you won’t see it again.

### Using Your API Key

Include your key in the `Authorization` header for every request. Also provide your workspace ID:

```
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/json
```

Example (list posts):

```
curl -X GET https://app.publer.com/api/v1/posts \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1"
```

### API Key Scopes

When creating an API key, you must select specific permission scopes based on your integration needs:

| Scope      | Description                                    | Example Endpoints         |
|------------|------------------------------------------------|---------------------------|
| `workspaces` | Retrieve user's workspaces                    | `/workspaces`             |
| `accounts`   | Retrieve user's accounts of selected workspace | `/accounts`               |
| `posts`      | Manage user's posts                            | `/posts`                  |
| `media`      | Upload and list media assets                   | `/media`                  |

### Common Authentication Errors

- **401 Unauthorized**  
  • Missing or invalid `Authorization` header  
  • Key revoked or expired

- **403 Forbidden**  
  • Insufficient scopes for the endpoint  
  • Missing `Publer-Workspace-Id` header

Always inspect the JSON error response for `message` and `code`.

### Security Best Practices

- **Environment Variables**  
  Store your key outside code—e.g., in a `.env` file:

```
PUBLER_API_KEY=your_api_key_here
```

- **Secrets Management**  
  Use a vault (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).
- **Key Rotation**  
  Rotate keys every 90–180 days, or after team changes/incidents.
- **Least Privilege**  
  Create separate keys for different use cases.
- **Safe Logging**  
  Never log full keys; mask all but the last 4 characters:

```
console.log(`Using key ***${apiKey.slice(-4)}`);
```

- **Always HTTPS**  
  Never send keys over plain HTTP.

### Troubleshooting

If you continue to see authentication errors:

1. Confirm your key is active and not expired.
2. Verify you have the correct header names and values.
3. Double-check that your key has the required scopes.
4. Contact support for assistance.