> ## Documentation Index
> Fetch the complete documentation index at: https://docs.urbanora.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> Clé API, header X-Api-Key, rotation, environnements test et live, Bearer pour le MCP.

L'API partenaire s'authentifie par **clé machine**. Ce n'est pas le JWT du SaaS Urbanora.

## Header

```http theme={null}
X-Api-Key: upk_live_…
```

Alias accepté (MCP, et tout client qui préfère Bearer) :

```http theme={null}
Authorization: Bearer upk_live_…
```

Sans clé, clé révoquée, expirée ou mal formée : `401 UNAUTHORIZED`. La réponse ne révèle pas si un préfixe existe.

## Test et live

| Préfixe | Usage |
| - | - |
| `upk_test_…` | Recette, playground, agents de développement |
| `upk_live_…` | Production |

Les deux se créent depuis le compte Urbanora. Une clé `test` et une clé `live` sont des secrets distincts : révoquer l'une ne touche pas l'autre.

## Scopes

Chaque clé porte une liste de périmètres. Un appel hors scope répond `403 FORBIDDEN`.

| Scope | Routes |
| - | - |
| `meta` | `/v1/meta/sources`, `/v1/meta/usage` |
| `buildings` | `/v1/buildings/qualify` |
| `imb` | `/v1/imb/…` |
| `copros` | `/v1/copros/…` |
| `syndics` | `/v1/syndics/…` |
| `search` | `/v1/search/…` |
| `zones` | `/v1/zones/…` |
| `contacts` | `/v1/contacts/…` |
| `owners` | Champ `proprietaires` dans qualify — **off** par défaut |

Demandez l'ouverture d'un scope à votre contact Urbanora. Ne mettez pas `owners` sur une clé de recette « par confort ».

## Rotation

1. Créez une nouvelle clé (même environnement, mêmes scopes).
2. Déployez-la côté client.
3. Révoquez l'ancienne.

La révocation est immédiate. La clé plaintext n'est **jamais** relue : seul un hash est stocké. Si vous la perdez, créez-en une autre.

> [!WARNING]
>
> Ne loggez pas la clé. Ne la commitez pas. Ne la placez pas dans une URL, un ticket ou un dump Sentry.

## MCP

Le serveur MCP (`https://mcp.urbanora.fr/mcp`) **forward** la même clé vers l'API REST. Il ne vérifie pas le hash lui-même. Voir [MCP](https://docs.urbanora.fr/guides/mcp.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.