# Authentication

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**](https://publer.com/help/en/article/how-to-access-the-publer-api-1w08edo/).
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:

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

Example (list posts):

```bash
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:

<table data-header-hidden><thead><tr><th width="134.11492919921875"></th><th width="407.987548828125"></th><th></th></tr></thead><tbody><tr><td>Scope</td><td>Description</td><td>Example Endpoints</td></tr><tr><td><code>workspaces</code></td><td>Retrieve user's workspaces</td><td><code>/workspaces</code></td></tr><tr><td><code>accounts</code></td><td>Retrieve user's accounts of selected workspace</td><td><code>/accounts</code></td></tr><tr><td><code>posts</code></td><td>Manage user's posts</td><td><code>/posts</code></td></tr><tr><td><code>media</code></td><td>Upload and list media assets</td><td><code>/media</code></td></tr></tbody></table>

### 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:

  ```bash
  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@publer.com> for assistance.

### Related Documentation

* [Quickstart Guide](https://publer.com/docs/getting-started/quickstart)
* [Rate Limits](https://publer.com/docs/getting-started/rate-limits)
* [API Reference](https://publer.com/docs/api-reference)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://publer.com/docs/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.