# Comptes de service et jetons

Un script, une intégration continue ou un outil interne appelle Bastide avec un jeton. Cette page explique quel jeton choisir, le jeton personnel ou le jeton de compte de service, comment les frapper, les faire tourner et les révoquer, et comment déployer depuis une intégration continue.

## Deux sortes de jetons

| | Jeton personnel | Jeton de compte de service |
| --- | --- | --- |
| Préfixe | `pat_` | `tok_` |
| Qui agit | Vous : le journal d'audit vous nomme. | Le jeton lui-même : il est le sujet de l'appel, et une personne nommée en répond. |
| Ce qu'il ouvre | Tout ce que votre rang ouvre, dans la limite de ses portées. | Une liste explicite de projets de l'organisation, de 1 à 20, avec un rang sur chacun, dans la limite de ses portées. |
| Ce qu'il fait | Tout ce que vous faites, hors des gestes réservés à une session de console. | Les lectures des projets nommés ; parmi les écritures, déployer et annuler un déploiement, rien d'autre. |
| Durée | De 1 à 365 jours. | De 1 à 90 jours. |
| Plafond | 50 jetons en vigueur par compte. | 50 jetons en vigueur par organisation. |
| Où le frapper | **Compte**, section « Vos jetons ». | **Membres**, carte « Comptes de service ». |

Préférez un compte de service pour une intégration continue : il survit au départ d'un membre tant que la personne qui en répond reste active, il n'ouvre que les projets nommés, et il ne peut ni modifier ni supprimer quoi que ce soit hors du déploiement.

Les deux sont rendus une seule fois, à leur création : Bastide n'en garde qu'une empreinte. Leurs portées et leur échéance sont fixées à la création ; un jeton ne se modifie pas, il se remplace.

## Le jeton personnel

### Le frapper

1. Ouvrez **Compte**, section « Vos jetons », puis **Frapper un jeton**.
2. Dites à quoi il sert : ce nom se relit dans la liste.
3. Choisissez sa durée de vie : 7, 30, 90, 180 ou 365 jours. La console propose 90 jours.
4. Cochez ses portées. La console n'offre que les portées que porte votre session ; un jeton ne donne jamais ce qu'il n'a pas.
5. Copiez le jeton affiché : il ne sera plus montré.

`bastide login` frappe aussi un jeton personnel, de 90 jours et à toutes les portées, rangé dans le trousseau du poste. Voir [La ligne de commande](cli.md).

### Son cycle de vie

- Il échoit à la date choisie, au plus un an après sa création.
- Inutilisé pendant 90 jours, il est désactivé. Vous êtes prévenu sept jours avant. Un jeton désactivé se réactive depuis **Compte** ; la réactivation exige une session de console.
- **Révoquer** le refuse dès l'appel suivant.
- La liste montre pour chacun ses portées, son échéance, son dernier usage et l'adresse de cet usage.

## Le compte de service

### Le frapper

Il faut le rang Administrateur sur l'organisation, et la portée `org:admin`.

1. Ouvrez **Membres**, carte « Comptes de service », puis **+ Frapper un compte de service**.
2. Nommez son usage, choisissez sa durée (de 1 à 90 jours) et ses portées.
3. Ajoutez les projets qu'il ouvre, chacun avec un rang : Lecteur, Développeur, Mainteneur, Administrateur ou Propriétaire. Vous ne pouvez pas lui donner un rang plus haut que le vôtre sur le projet, ni une portée que votre session ne porte pas.
4. **Frapper le jeton**, puis copiez-le. La carte propose une commande de vérification qui lit son premier projet.

Vous en répondez : la fiche vous nomme. Si votre compte est suspendu ou supprimé, le jeton passe à l'état `orphaned` et n'ouvre plus rien.

Par l'API, l'opération est `service_token.create` :

```json
{
  "name": "Déploiement depuis l'intégration continue",
  "scopes": ["project:read", "deploy:write"],
  "expiresInDays": 90,
  "projects": [{ "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567", "role": "developer" }]
}
```

### Ce qu'il peut faire

Un compte de service n'a personne derrière lui. La plateforme lui ferme donc tout ce qui suppose une personne :

- Il lit, sur ses projets, ce que son rang et ses portées permettent : projets, environnements, déploiements, journaux, journal d'audit.
- Parmi les écritures, il ne mène que `deployment.create` et `deployment.cancel`. Toute autre écriture est refusée en `service_action_forbidden`. La page de référence de chaque opération dit, ligne « Compte de service », ce qu'il en fait.
- Il ne valide jamais une opération irréversible (`validation_humaine_requise`).
- Il n'atteint rien au-dessus de ses projets : ni l'organisation, ni la facturation.

Si l'organisation exige un second facteur, un compte de service peut en être exempté nommément, avec un motif, pour 92 jours au plus : **Réglages** de l'organisation, section « Second facteur ».

### La revue

La carte « Comptes de service » est la revue : chaque jeton, ouvert ou fermé, avec ses portées, ses projets et leur rang, la personne qui en répond, son échéance et son dernier usage. Relisez-la chaque trimestre, et révoquez ce qui ne sert plus. La révocation est définitive et se confirme dans une fenêtre qui nomme le jeton.

## Faire tourner un jeton

Aucun jeton ne se prolonge. Pour le remplacer sans coupure :

1. Frappez un nouveau jeton, mêmes portées et mêmes projets.
2. Remplacez-le dans le secret de votre intégration continue ou de votre outil.
3. Vérifiez un appel avec le nouveau jeton.
4. Révoquez l'ancien.

Un jeton Bastide repéré dans un dépôt pendant une construction est révoqué automatiquement, et la personne qui en répond est prévenue : frappez-en un autre et ne le versionnez pas.

## Déployer depuis une intégration continue

La ligne de commande lit le jeton dans `BASTIDE_TOKEN` et ne consulte alors rien d'autre. Un compte de service au rang Développeur, avec les portées `project:read` et `deploy:write`, suffit à `bastide deploy`.

Exemple pour GitHub Actions, le jeton rangé dans le secret `BASTIDE_TOKEN` du dépôt :

```yaml
name: Déployer
on:
  push:
    branches: [main]
jobs:
  deployer:
    runs-on: ubuntu-latest
    steps:
      - run: npx --yes bastide deploy --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567 --ref "$GITHUB_SHA"
        env:
          BASTIDE_TOKEN: ${{ secrets.BASTIDE_TOKEN }}
```

`bastide deploy` sort avec le code 0 si le déploiement sert, 13 s'il échoue ou n'est pas mis en service : l'étape échoue avec lui. Les autres codes sont dans [La ligne de commande](cli.md).

Sans la ligne de commande, appelez l'API directement : `POST /v1/projects/{projectId}/deployments` avec une clé d'idempotence, puis suivez le travail par `task.read`. Voir [L'API HTTP](api.md).

> **Conseil.** Pour un déploiement déclenché par un simple appel d'adresse, sans jeton, un crochet de déploiement suffit : il se crée sur l'écran **Webhooks** du projet. Voir [Les webhooks](webhooks.md).

## Erreurs fréquentes

| Code | Cause | Remède |
| --- | --- | --- |
| `unauthenticated` | Jeton échu, révoqué, désactivé, ou responsable inactif. | Frappez-en un autre. |
| `service_action_forbidden` | L'écriture n'est pas ouverte aux comptes de service. | Utilisez un jeton personnel, ou faites le geste depuis la console. |
| `token_scope_missing` | Le jeton ne porte pas la portée. | Frappez un jeton avec la portée. |
| `insufficient_rank` | Le rang donné sur le projet est trop bas. | Frappez un jeton avec un rang suffisant. |
| `not_found` | Le projet n'est pas dans la liste du jeton. | Frappez un jeton qui le nomme. |
| `quota_de_jetons_de_service_atteint` | 50 jetons en vigueur dans l'organisation. | Révoquez ceux qui ne servent plus. |
| `quota_de_jetons_personnels_atteint` | 50 jetons en vigueur sur votre compte. | Révoquez ceux qui ne servent plus. |

## Voir aussi

- [L'API HTTP](api.md)
- [La ligne de commande](cli.md)
- [Ce qu'un agent peut faire](agent-safety.md)
- [Organisations et membres](organizations.md)