Authentification

Authentification par clé API

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Les clés ont la forme ucos_<live|test>_<32 caractères base64url>, par exemple ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. Conservez-les côté serveur et renouvelez toute clé qui apparaît dans un journal ou une capture d'écran.

Génération de clés API

1. Connectez-vous à votre tableau de bord Ultimate Custom Order Status
2. Accédez à Paramètres > Clés API
3. Cliquez sur "Générer une nouvelle clé API"
4. Configurez les permissions pour votre clé API
5. Enregistrez la clé API en toute sécurité (elle ne sera affichée qu'une seule fois)

Gestion des clés API

• Le nom d’affichage et la description sont modifiables à tout moment.
• Le secret de la clé, les permissions, les limites de débit et l’expiration sont fixés à la création et ne peuvent plus être modifiés ensuite.
• Pour modifier l’un de ces éléments, révoquez la clé et créez une clé de remplacement. Une clé révoquée reste listée et refuse l’authentification jusqu’à la suppression de son enregistrement.
• Les limites de débit sont définies par clé à la création (par défaut : 60 requêtes par minute et 10 000 par jour) et sont indiquées dans les en-têtes de réponse X-RateLimit-*.
• La carte des clés liste les dernières requêtes servies par chaque clé, ce qui rend l’utilisation vérifiable dans l’application.

Permissions de clé API

Limitation de débit

• Limite par minute : définie par clé à la création (par défaut : 60 requêtes/minute)
• Limite par jour : définie par clé à la création (par défaut : 10 000 requêtes/jour)

Une requête qui dépasse l'une des limites est rejetée avec 429, un en-tête Retry-After et details.retryAfter dans le corps.

Les informations de limite de débit sont incluses dans tous les en-têtes de réponse API:

• X-RateLimit-Limit-Minute: Nombre maximum de requêtes par minute
• X-RateLimit-Remaining-Minute: Requêtes restantes dans la minute en cours
• X-RateLimit-Reset-Minute: Horodatage Unix (secondes) de réinitialisation de la minute
• X-RateLimit-Limit-Day: Nombre maximum de requêtes par jour
• X-RateLimit-Remaining-Day: Requêtes restantes dans le jour en cours
• X-RateLimit-Reset-Day: Horodatage Unix (secondes) de réinitialisation du jour
• Retry-After: Secondes à attendre avant de réessayer (présent en cas de limitation)

Meilleures pratiques de sécurité

Journal d’audit

• Les requêtes authentifiées enregistrent le point de terminaison, la méthode, le code de statut, le temps de réponse, l’adresse source et l’agent utilisateur.
• Une requête en échec (4xx ou 5xx) enregistre aussi le corps de la requête et le message d’erreur de la réponse, afin qu’une charge utile rejetée puisse être diagnostiquée depuis le journal.
• Une requête rejetée avant l’authentification (clé absente ou inconnue, 401) ne produit pas de ligne par clé ; l’application enregistre la tentative séparément (raison, quatre derniers caractères de la clé présentée, source et point de terminaison) pour le support.
• Les deux types d’enregistrements sont conservés 90 jours par défaut, puis supprimés.
• Une clé révoquée ou expirée présentée est enregistrée comme un 401 (afin qu’une clé retirée toujours utilisée reste visible) mais ne compte pas comme une utilisation.
• Le compteur d’utilisation et la date de dernière utilisation de la clé sont mis à jour exactement une fois par requête authentifiée, y compris les requêtes refusées par un contrôle de permission ou par la limite de débit.

Exemple de requête

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Réponses d'erreur

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

{
  "success": false,
  "error": "Insufficient permissions. Required: canViewOrders"
}

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["status_id"],
        "message": "Required"
      }
    ]
  }
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "retryAfter": 30
  }
}

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}