# Authentication

URL: https://wa.genuka.com/en/docs/authentication
Language: English

> API keys, scope, and rotation practices.

Every request authenticates with an API key in the `Authorization` header:

```http
Authorization: Bearer pk_live_...
```

> [!WARNING]
> You **never** handle a Meta token. Genuka WA holds the Cloud API credentials and rotates them
> for you: one Genuka API key is enough, and it only reaches your own data.

## Two key scopes

| Scope       | Access                      | Use case                                           |
| ----------- | --------------------------- | -------------------------------------------------- |
| **Partner** | Every client of the partner | A platform managing numbers for several businesses |
| **Client**  | A single business           | A business integrating only its own numbers        |

A client key reaching for another business gets `403 out_of_scope`. Some endpoints — billing,
plan usage — require a partner key and answer `403 partner_key_required` otherwise.

## Creating and revoking a key

Keys are managed from the portal, under **Developers**. A key is shown **once** at creation:
Genuka stores only a fingerprint and cannot show it to you again.

To rotate without downtime: create the new key, deploy it, confirm traffic in the logs, then
revoke the old one.

## Error responses

| Status | Code                   | Meaning                                   |
| ------ | ---------------------- | ----------------------------------------- |
| `401`  | `missing_bearer_token` | No `Authorization` header                 |
| `401`  | `invalid_token`        | Unknown or revoked key                    |
| `403`  | `out_of_scope`         | The key is restricted to another business |
| `403`  | `partner_key_required` | Endpoint reserved for partner keys        |

## Security

* An API key is a server-side secret. Never ship it in a frontend or a mobile app — anyone could
  send messages in your name, at your expense.
* Use distinct keys per environment and per integration: revoking then becomes surgical rather
  than global.
* Every request is logged and visible in the portal.
