> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-fr/kilo-center/kilo-mioty-service-center/integrations/api-reference.md).

# Référence de l’API

Référence de l’API gRPC de KiloCenter — définitions Protocol Buffer pour les stations de base, les points de terminaison, avec portail en ligne.

KiloCenter fournit une API gRPC pour intégrer ou étendre la plateforme. Toutes les définitions d’API sont des Protocol Buffers hébergés dans le dépôt sous `KC-Core/api/proto/`.

### Référence API interactive

Une référence API navigable avec tous les points de terminaison RPC est disponible à :

<https://servicecenter-api.kiloiot.io/>

### Présentation de gRPC

gRPC est un framework RPC hautes performances qui utilise Protocol Buffers pour la sérialisation et HTTP/2 pour le transport. Pour plus d’informations, voir [grpc.io](https://grpc.io/).

L’API de KiloCenter est définie dans trois fichiers proto :

| Fichier            | Description                                                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `kilocenter.proto` | Service unifié rétrocompatible (117 RPC au total)                                                                                      |
| `core.proto`       | Messages du domaine central (points de terminaison, stations de base, messages, liaisons descendantes, événements, certificats, plans) |
| `identity.proto`   | Messages du domaine d’identité (utilisateurs, organisations, clés API, authentification)                                               |

### Génération de client

**Go (avec buf — valeur par défaut du projet) :**

```bash
cd KC-Core/api/proto && buf generate
```

Sortie : `KC-Core/api/gen/` (uniquement des stubs Go — `buf.gen.yaml` configure les plugins Go).

**Autres langages (avec protoc) :**

```bash
# Exemple Python
python -m grpc_tools.protoc \\
  -I KC-Core/api/proto \\
  --python_out=./gen --grpc_python_out=./gen \\
  KC-Core/api/proto/kilocenter.proto \\
  KC-Core/api/proto/core.proto \\
  KC-Core/api/proto/identity.proto
```

`buf.gen.yaml` génère uniquement des stubs Go. Pour les autres langages, utilisez protoc ou ajoutez des plugins buf. Voir [grpc.io/docs/languages](https://grpc.io/docs/languages/) pour des guides spécifiques à chaque langage.

### Authentification

#### Édition communautaire

L’édition Community s’exécute avec l’authentification désactivée (`KILOCENTER_AUTH_ENABLED=false`). Aucun en-tête n’est requis pour aucun RPC — toutes les méthodes sont accessibles directement.

```bash
# Aucun en-tête d’authentification nécessaire
grpcurl -plaintext -d '{}' \\
  localhost:9090 kilocenter.api.v1.KiloCenterService/GetSystemStatus
```

#### Édition Entreprise

Lorsque l’authentification est activée (`KILOCENTER_AUTH_ENABLED=true`), trois en-têtes de métadonnées s’appliquent :

| En-tête             | Requis pour                                                            | Valeur                                     |
| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------ |
| `authorization`     | Tous les RPC non publics                                               | `Bearer <JWT_TOKEN>` ou `Bearer <API_KEY>` |
| `x-organization-id` | Tous les RPC non exemptés                                              | UUID de l’organisation cible               |
| `x-user-id`         | RPC appelés sans JWT (mode d’authentification par en-têtes uniquement) | UUID de l’utilisateur agissant             |

**Méthodes publiques** (aucun en-tête requis) : `Connexion`, `RefreshTokens`, `GetAuthSettings`, `ExchangeOIDC`, `ExchangeOAuth2`, `GetReleaseInfo`, `RegisterAccount` Source : `KC-Core/pkg/grpc/public_methods.go`

**Méthodes exemptées d’organisation** (authentification requise, aucun en-tête d’organisation) : `GetSystemStatus`, `GetProfile`, `Déconnexion`, `ChangePassword`, CRUD Utilisateur/Organisation/Adhésion (contexte d’organisation résolu à partir des champs de la requête) Source : `KC-Core/pkg/grpc/public_methods.go` → `OrgExemptMethods`

Les jetons d’API sont créés via KC-Web ou le `CreateApiKey` RPC.

### Référence API par domaine

#### Points de terminaison (7)

`CreateEndPoint`, `GetEndPoint`, `UpdateEndPoint`, `DeleteEndPoint`, `ListEndPoints`, `AttachEndPoint`, `DetachEndPoint`

#### Stations de base (7)

`CreateBaseStation`, `GetBaseStation`, `UpdateBaseStation`, `DeleteBaseStation`, `ListBaseStations`, `GetBaseStationStats`, `UpdateBaseStationEui`

#### Messages (11)

`GetMessage`, `ListMessages`, `StreamMessages`, `ListBaseStationMessages`, `GetBaseStationMessage`, `GetBaseStationMessageStats`, `SearchBaseStationMessages`, `ExportBaseStationMessages`, `StreamBaseStationMessages`, `ListEndpointMessages`, `ListBaseStationActivity`

#### Liaisons descendantes (4)

`SendDownlink`, `RevokeDownlink`, `ListDownlinkQueue`, `GetDownlinkResults`

#### Transmission UL (1)

`SendULTransmit`

#### Contrôle des stations de base (2)

`RequestBaseStationStatus`, `InitiatePing`

#### Statut de réception DL (3)

`GetDLRXStatus`, `QueryDLRXStatus`, `GetDLRXStatusQueries`

#### Système (3)

`GetSystemStatus`, `GetStatistics`, `GetReleaseInfo`

#### Clés API (4)

`CreateApiKey`, `GetApiKey`, `DeleteApiKey`, `ListApiKeys`

#### Intégrations (5)

`CreateIntegration`, `GetIntegration`, `UpdateIntegration`, `DeleteIntegration`, `ListIntegrations`

#### Analytique (3)

`GetAnalyticsOverview`, `GetActivityAnalytics`, `GetSignalQualityAnalytics`

#### Événements et alertes (8)

`ListEvents`, `ListBaseStationEvents`, `ListEndPointEvents`, `StreamEvents`, `StreamBaseStationEvents`, `StreamEndPointEvents`, `ListAlerts`, `GetAlertSummary`

#### Surveillance SCACI (6)

`ListScaciSessions`, `GetScaciSession`, `GetScaciStatistics`, `ListScaciErrors`, `ListScaciQueues`, `GetScaciStatus`

#### Certificats (6)

`GenerateCertificate`, `DownloadCertificate`, `DownloadBaseStationCertificate`, `GenerateServerCertificates`, `RenewServerCertificates`, `GetServerCertificateStatus`

#### Fabricants (5)

`CreateManufacturer`, `GetManufacturer`, `UpdateManufacturer`, `DeleteManufacturer`, `ListManufacturers`

#### Modèles d’appareils (5)

`CreateDeviceModel`, `GetDeviceModel`, `UpdateDeviceModel`, `DeleteDeviceModel`, `ListDeviceModels`

#### Plans (8)

`CreateBlueprint`, `GetBlueprint`, `UpdateBlueprint`, `DeleteBlueprint`, `ListBlueprints`, `SetDefaultBlueprint`, `SubmitBlueprintToRegistry`, `CreateDeviceModelWithBlueprint`

#### Utilitaires de plans (1)

`DecodePreview`

#### Statistiques des points de terminaison (2)

`GetEndPointStats`, `GetEndPointOperations`

#### Auth et session (8) — Entreprise

`Connexion`, `RefreshTokens`, `GetProfile`, `GetAuthSettings`, `Déconnexion`, `ChangePassword`, `ExchangeOIDC`, `ExchangeOAuth2`

#### Inscription en libre-service (1) — Entreprise

`RegisterAccount`

#### Utilisateurs (6) — Entreprise

`CreateUser`, `GetUser`, `UpdateUser`, `DeleteUser`, `ListUsers`, `UpdateUserPassword`

#### Organisations (5) — Entreprise

`CreateOrganization`, `GetOrganization`, `UpdateOrganization`, `DeleteOrganization`, `ListOrganizations`

#### Adhésions aux organisations (6) — Entreprise

`AddOrganizationUser`, `GetOrganizationUser`, `UpdateOrganizationUser`, `RemoveOrganizationUser`, `ListOrganizationUsers`, `ListUserOrganizations`

### RPC en streaming

Cinq RPC utilisent le streaming côté serveur pour fournir des données en temps réel :

| RPC                         | Cas d’utilisation                          |
| --------------------------- | ------------------------------------------ |
| `StreamMessages`            | Messages de liaison montante en temps réel |
| `StreamBaseStationMessages` | Flux de messages de la station de base     |
| `StreamEvents`              | Notifications d’événements système         |
| `StreamBaseStationEvents`   | Flux d’événements de la station de base    |
| `StreamEndPointEvents`      | Flux d’événements du point de terminaison  |

```typescript
const stream = client.streamMessages(request, metadata);
stream.on('data', (message) => { /* handle message */ });
stream.on('error', (err) => { /* handle error */ });
stream.on('end', () => { /* stream closed */ });
```

### Pagination

Tous `List*` Les RPC prennent en charge la pagination basée sur un offset via `page_size` et `page_token` champs.

**RPC de liste standard :** 20 par défaut, 100 max **Listes à fort volume** (points de terminaison, stations de base, liaisons descendantes) : 100 par défaut, 1000 max

Source : `KC-Core/pkg/grpc/pagination.go`

```protobuf
message ListEndPointsRequest {
  int32 page_size = 1;    // 20 par défaut, 100 max
  string page_token = 2;  // Depuis ListEndPointsResponse.next_page_token précédent
}
```

### Gestion des erreurs

Toutes les erreurs utilisent les codes d’état gRPC avec des jetons d’erreur lisibles par machine provenant de `KC-Core/pkg/grpc/errors_catalog.go`.

| Code gRPC                 | Équiv. HTTP | Causes courantes                         |
| ------------------------- | ----------- | ---------------------------------------- |
| `INVALID_ARGUMENT` (3)    | 400         | Requête mal formée, échecs de validation |
| `NOT_FOUND` (5)           | 404         | La ressource n’existe pas                |
| `ALREADY_EXISTS` (6)      | 409         | Ressource en double                      |
| `PERMISSION_DENIED` (7)   | 403         | Échec d’autorisation                     |
| `UNAUTHENTICATED` (16)    | 401         | Jeton manquant ou invalide               |
| `FAILED_PRECONDITION` (9) | 400         | Échec lié à l’état                       |
| `INTERNAL` (13)           | 500         | Erreur serveur                           |

Pour le modèle d’erreur complet et les plages de jetons d’erreur, voir docs/api.md.

### Console API

La réflexion gRPC est activée sur KC-Gateway. Outils compatibles :

```bash
# grpcui — interface web interactive
grpcui -plaintext localhost:9090

# grpcurl — client en ligne de commande
grpcurl -plaintext localhost:9090 list

# Postman — utilisez l’onglet gRPC avec la réflexion serveur
# BloomRPC — client gRPC de bureau
```

### Pour aller plus loin

* Référence API complète — contrats requête/réponse et plages de jetons d’erreur
* Fichiers sources Proto — définitions canoniques de l’API
* Premiers pas avec gRPC — vérifier la connectivité et découvrir les méthodes


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-docs-fr/kilo-center/kilo-mioty-service-center/integrations/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.