Accès API

Authentifier une requête

Utilisez https://allocyn.com/api/public/v1 pour le service hébergé. Pour un autre déploiement, utilisez son domaine HTTPS et son éventuel chemin de base, par exemple https://example.com/allocyn/api/public/v1.

Envoyez la clé complète dans X-Allocyn-Key. Un jeton Bearer, un secret de webhook ou un cookie de connexion du navigateur ne peut pas la remplacer. Configurez ALLOCYN_API_KEY de manière sécurisée avant d’exécuter l’exemple PowerShell ; il effectue une requête de lecture.

GET /api/public/v1/projects?page=1&pageSize=100 HTTP/1.1
Host: allocyn.com
Accept: application/json
X-Allocyn-Key: <your-api-key>

$apiBase = 'https://allocyn.com/api/public/v1'
if ([string]::IsNullOrWhiteSpace($env:ALLOCYN_API_KEY)) {
    throw 'Set ALLOCYN_API_KEY securely before running this example.'
}
$apiHeaders = @{ 'X-Allocyn-Key' = $env:ALLOCYN_API_KEY; Accept = 'application/json' }
$page = Invoke-RestMethod -Method Get -Uri "$apiBase/projects?page=1&pageSize=100" -Headers $apiHeaders
$page.data | Select-Object code, name, status, health

Ressources et autorisations prises en charge

Ces routes sont relatives à l’URL de base de l’API publique et acceptent GET. Aucun point de terminaison public ne permet de modifier ces ressources, saisir du temps, générer ou télécharger des rapports, ni gérer les clients et les webhooks avec une clé API.

Pagination

Chaque ressource renvoie data et meta. Augmentez page tant que meta.hasMore vaut true. La valeur returned compte uniquement les éléments de cette page ; une page au-delà des données disponibles contient un tableau data vide.

Les projets sont triés par code, les éléments de travail par titre et les personnes par nom d’affichage, tous par ordre croissant ; les rapports sont triés par date de génération décroissante. La pagination n’est pas un instantané : les modifications et les valeurs de tri identiques peuvent déplacer les limites des pages. Dédupliquez par id et rapprochez régulièrement les données. Aucun filtrage, tri personnalisé ou paramètre modified-since n’est pris en charge.

{
  "data": [{
    "id": "11111111-1111-7111-8111-111111111111",
    "code": "CLIENT-PORTAL",
    "name": "Client portal",
    "status": "Active",
    "health": "OnTrack",
    "startsOn": "2026-09-01",
    "currentTargetEndDate": "2026-11-30"
  }],
  "meta": { "page": 1, "pageSize": 100, "returned": 1, "hasMore": false }
}

Référence des champs de réponse

Ces champs figurent dans chaque objet data. Les identifiants sont des chaînes opaques, les valeurs status et health sont des noms d’énumération du serveur, les dates seules utilisent YYYY-MM-DD et les horodatages UTC utilisent ISO 8601. Les champs facultatifs peuvent valoir null. Les identifiants d’enregistrements liés ne sont pas des URL de téléchargement.

Limites et erreurs

La limite du client est partagée entre ses requêtes à l’API publique dans des fenêtres fixes d’une minute UTC. Une limite globale distincte autorise 300 requêtes par minute et par adresse IP distante, partagées avec les autres requêtes issues de cette adresse. Un réglage client plus élevé ne contourne pas cette limite ; l’infrastructure d’hébergement peut imposer d’autres limites.

La limitation de débit du client renvoie 401 sans motif spécifique ni en-tête de réinitialisation. Après vérification des identifiants et des autorisations, réessayez après le début de la minute UTC suivante si la limite du client est en cause. Ne répétez pas les tentatives en cas de réponses 401 persistantes. Les messages d’erreur peuvent être traduits et les proxys peuvent renvoyer des corps différents.

{
  "status": 401,
  "title": "API access denied",
  "detail": "The API key is invalid, expired, revoked, outside its rate limit, or missing the required scope."
}

Périmètre de l’organisation et disponibilité

Une clé API appartient à une organisation. Dans les autorisations sélectionnées, elle lit les données de toute l’organisation, pas seulement les affectations de projet de son créateur. Aucun en-tête ni paramètre de requête ne permet à l’appelant de choisir l’organisation. Ne confiez la clé qu’aux services autorisés à recevoir ces informations.

Les appels nécessitent une organisation active, son module Intégrations activé, un abonnement éligible et un droit d’accès API activé. Un essai non expiré ou une période payante admissible peut autoriser l’accès ; un essai terminé ou la période de rétablissement d’un abonnement ne le permet pas. La création est également soumise à la limite configurée de clients API.

Remplacer ou révoquer une clé

Les clients existants ne permettent pas de réafficher ou renouveler leur clé, ni de modifier leurs autorisations ou leur expiration. Tenez compte de la limite de clients actifs pendant la coexistence des anciens et nouveaux clients. Si aucune place n’est disponible, coordonnez une interruption ou contactez votre administrateur.

• Créez un client de remplacement avec un nom distinct, les autorisations, la limite de débit et l’expiration nécessaires ; conservez sa nouvelle clé révélée.
• Mettez votre service à jour et confirmez qu’une lecture autorisée réussit, puis révoquez l’ancien client depuis Accès API.
• En cas de compromission suspectée, révoquez d’abord le client. La révocation empêche les authentifications futures, mais ne retire pas les données déjà lues et n’annule pas une requête déjà autorisée. Les clients révoqués restent dans la liste et ne peuvent pas être réactivés depuis cette interface.

Référence de gestion des clients API

Ces routes utilisent l’accès authentifié habituel à l’organisation, et non X-Allocyn-Key. Préfixez-les par /api/organization/integration-operations et l’éventuel chemin de base du déploiement. La consultation nécessite integrations.view ; la création et la révocation nécessitent également integrations.manage.

Un résumé de client contient id, name, requestsPerMinute, expiresAtUtc, isActive, keyPrefix, lastUsedAtUtc, permissions et version. Envoyez la dernière valeur opaque Base64 de version lors de la révocation ; rechargez après un conflit 409. Les erreurs de validation renvoient 400 et les échecs d’authentification ou d’autorisation peuvent renvoyer 401 ou 403.

Expiration et résolution des problèmes

Dans les requêtes de gestion, indiquez pour expiresAtUtc un horodatage UTC futur, comme 2027-01-01T00:00:00Z, ou null. Le champ d’expiration du portail ne convertit pas explicitement sa date et heure locales en UTC avant l’envoi. Vérifiez l’expiration enregistrée sans présumer d’une conversion de fuseau horaire. Les clients expirés mais non révoqués comptent toujours dans la limite de clients actifs.

Si la page ou le bouton de création est absent, vérifiez l’organisation sélectionnée, integrations.view, integrations.manage, l’accès lié à l’abonnement et les limites. Pour l’assistance, indiquez la route, l’heure UTC, le statut et l’en-tête de réponse X-Correlation-ID lorsqu’il est disponible. N’envoyez jamais votre clé API.