> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/basics/authentification.md).

# Authentication

#### Authentication

Authentication is mandatory for all API requests:

* Requests must include an API key, generated on the **API / Plugin Keys** page of the [Cityweft dashboard](https://app.cityweft.com). Keys look like `cw_...`.
* The API key should be included in the request header as shown below:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```

For a step-by-step walkthrough of creating and managing keys, see [Getting your API key](/docs/plugins/getting-your-api-key.md).

#### Error responses

| Status | Meaning                                                                                                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`  | Missing or invalid API key.                                                                                                                                                                      |
| `402`  | No active subscription or remaining balance for this request — check **Plan & Billing** in the dashboard.                                                                                        |
| `429`  | The usage limit on this API key is pausing requests (`code: "USAGE_LIMIT_REACHED"`). It lifts when the limit resets (`resetsAt`) or is raised. See [Usage limits](/docs/basics/usage-limits.md). |
| `400`  | Invalid request body (e.g. malformed polygon, area larger than 10 km²). The response body describes the problem.                                                                                 |
| `503`  | Server busy — retry shortly (a `Retry-After` header is included).                                                                                                                                |

#### Security

To ensure the integrity and security of our service, the API implements various security protocols:

* **Requests Monitoring**: Requests are monitored continuously for unusual patterns to prevent abuse.
* **API Key Confidentiality**: Ensure API keys are safeguarded and never exposed in client-side code. If a key leaks, re-issue it from the dashboard — the old key is deactivated permanently.
* **HTTPS Usage**: All API requests must use HTTPS to secure data in transit and prevent interception.

#### Versioning

The API adheres to semantic versioning for structured and predictable release of changes:

* The current stable version is `v1`.
* Any breaking changes will be introduced in new versions, ensuring backward compatibility for existing implementations.