> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Convo API Authentication: Keys, Headers, and Security

> Convo uses API key authentication via HTTP headers. Learn how to obtain your credentials and pass them correctly on every request.

Convo authenticates all API requests via a single HTTP request header. There are no cookies, no OAuth flows, and no query-string tokens. Every request to the Convo API must include the `X-API-WA-Project-API-Pwd` header, or the server will respond with `401 Unauthorized`.

## Project API Password

**Header:** `X-API-WA-Project-API-Pwd`

The Project API Password is scoped to a single Convo project (and its associated WhatsApp number). It is used for all API operations, including sending messages, managing contacts, and triggering campaigns.

### How to obtain it

1. Log in to the [Convo Dashboard](https://app.convo.com).
2. Navigate to **Settings** → **API & Integrations**.
3. Copy the value labelled **Project API Password**.

This password is set once per project and remains valid until you regenerate it. Regenerating it will immediately invalidate the previous value, so update all your integrations if you rotate it.

### Example request

```bash theme={null}
curl -X POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "to": "917089379345",
    "type": "text",
    "recipient_type": "individual",
    "text": {
      "body": "Hello from Convo!"
    }
  }'
```

Replace `{project_id}` with your project's ID and `YOUR_API_PASSWORD` with the password you copied from the dashboard.

## Security Best Practices

API credentials give full programmatic access to your Convo account. Treat them with the same care as passwords.

* **Never expose keys in client-side code.** Do not embed the API password in browser JavaScript, mobile app binaries, or public repositories. Anyone who obtains your key can send messages on your behalf.
* **Use environment variables.** Store credentials in environment variables (e.g. `CONVO_API_PASSWORD`) and read them at runtime. This keeps secrets out of your codebase entirely.
* **Use a secrets manager in production.** For production workloads, store credentials in a dedicated secrets manager such as AWS Secrets Manager, HashiCorp Vault, or GCP Secret Manager, and inject them into your application at startup.
* **Rotate keys if compromised.** If you believe a key has been exposed, regenerate it immediately from the Convo dashboard and update all affected integrations.

<Warning>
  Never hard-code API keys directly in your source code. If your repository is ever made public — intentionally or accidentally — exposed credentials can be exploited immediately. Always use environment variables or a secrets manager to inject credentials at runtime.
</Warning>

## Error Responses

When authentication fails or a request is malformed, Convo returns a standard HTTP error status code alongside a JSON body describing the problem.

| Status Code | Meaning                                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | **Bad Request** — The request is missing required parameters or contains invalid values.                                         |
| `401`       | **Unauthorized** — The API key or access code is missing, expired, or incorrect.                                                 |
| `404`       | **Not Found** — The requested resource (project, contact, template, etc.) does not exist.                                        |
| `409`       | **Conflict** — The resource you're trying to create already exists.                                                              |
| `500`       | **Internal Server Error** — Something went wrong on Convo's side. Retry with backoff, and contact support if the issue persists. |

### Example error response

The response body follows a consistent structure with `name` and `message` fields:

```json theme={null}
{
  "name": "ERR400",
  "message": "Invalid Business ID!"
}
```

Use the `name` field for programmatic error handling in your code, and the `message` field to understand what specifically went wrong. For `401` errors, verify that you are sending the correct header name and that the credential value has not expired or been regenerated.