L'API Veasy Global supporte deux méthodes d'authentification : le Bearer Token pour les environnements de développement et d'intégration, et le mTLS (mutual TLS) pour les déploiements de production classifiés. Ce guide vous explique comment obtenir vos credentials, faire vos premiers appels authentifiés, et configurer mTLS pour les environnements à haute sécurité.
The Veasy Global API supports two authentication methods: Bearer Token for development and integration environments, and mTLS (mutual TLS) for classified production deployments. This guide explains how to obtain your credentials, make your first authenticated calls, and configure mTLS for high-security environments.
1. Obtenir votre clé API
1. Obtaining your API key
Les clés API Veasy Global sont émises par votre Technical Account Manager (TAM) lors de l'activation de votre compte. Elles ne peuvent pas être générées automatiquement depuis le portail — cette mesure garantit que chaque clé est liée à une entité contractante vérifiée et à un niveau d'habilitation validé.
Veasy Global API keys are issued by your Technical Account Manager (TAM) upon account activation. They cannot be self-generated from the portal — this measure ensures each key is bound to a verified contracting entity and a validated clearance level.
Chaque clé API est associée à :
Each API key is associated with:
- Un identifiant d'organisation unique (
org_id)
- A unique organisation identifier (
org_id)
- Un ou plusieurs scopes de permissions (ex.
g2:read, sentinel:write, guard:cameras)
- One or more permission scopes (e.g.
g2:read, sentinel:write, guard:cameras)
- Une date d'expiration (90 jours par défaut, renouvelable)
- An expiry date (90 days by default, renewable)
- Un environnement cible :
sandbox, staging, ou production
- A target environment:
sandbox, staging, or production
Bonne pratique :
Best practice:
Ne stockez jamais votre clé API en clair dans votre code source. Utilisez des variables d'environnement ou un gestionnaire de secrets (HashiCorp Vault, AWS Secrets Manager).
Never store your API key in plaintext in your source code. Use environment variables or a secrets manager (HashiCorp Vault, AWS Secrets Manager).
2. Authentification par Bearer Token
2. Bearer Token Authentication
Le Bearer Token est la méthode d'authentification recommandée pour les environnements de développement, les scripts d'automatisation et les intégrations CI/CD. Chaque requête doit inclure l'en-tête Authorization avec le préfixe Bearer.
The Bearer Token is the recommended authentication method for development environments, automation scripts, and CI/CD integrations. Every request must include the Authorization header with the Bearer prefix.
Exemple avec cURL
Example with cURL
curl -X GET https://api.veasyglobal.com/v1/g2/missions \
-H "Authorization: Bearer vg_live_XXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-H "X-Org-ID: org_XXXXXXXXXXXXXXXX"
Exemple avec Python (requests)
Example with Python (requests)
import requests
API_KEY = "vg_live_XXXXXXXXXXXXXXXXXXXX"
ORG_ID = "org_XXXXXXXXXXXXXXXX"
BASE_URL = "https://api.veasyglobal.com/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-Org-ID": ORG_ID,
}
response = requests.get(f"{BASE_URL}/g2/missions", headers=headers)
response.raise_for_status()
missions = response.json()
print(f"Missions actives : {missions['total']}")
Attention :
Warning:
Le Bearer Token ne doit jamais être utilisé en environnement de production classifié (SECRET ou au-dessus). Pour ces déploiements, le mTLS est obligatoire.
The Bearer Token must never be used in a classified production environment (SECRET or above). For these deployments, mTLS is mandatory.
3. Configuration mTLS pour la production
3. mTLS Configuration for Production
Le mTLS (mutual Transport Layer Security) établit une authentification bidirectionnelle entre votre client et les serveurs Veasy Global. Contrairement au Bearer Token, il garantit que seuls les clients possédant un certificat valide émis par l'autorité de certification Veasy Global peuvent établir une connexion — indépendamment du secret partagé.
mTLS (mutual Transport Layer Security) establishes bidirectional authentication between your client and Veasy Global servers. Unlike Bearer Token, it ensures that only clients holding a valid certificate issued by the Veasy Global certificate authority can establish a connection — independent of any shared secret.
Étape 1 — Générer une paire de clés et une CSR
Step 1 — Generate a key pair and CSR
01
Générer la clé privée et la CSR
Generate private key and CSR
openssl genrsa -out client.key 4096
openssl req -new -key client.key -out client.csr \
-subj "/CN=org_XXXXXXXXXXXXXXXX/O=VotreSociete/C=FR"
02
Soumettre la CSR à Veasy Global
Submit the CSR to Veasy Global
Envoyez le fichier client.csr à votre TAM par canal sécurisé (portail chiffré ou email signé S/MIME). Le délai d'émission est de 2 jours ouvrés.
Send the client.csr file to your TAM via secure channel (encrypted portal or S/MIME-signed email). Issuance lead time is 2 business days.
03
Recevoir et installer le certificat client
Receive and install the client certificate
Votre TAM vous remettra client.crt et le certificat CA intermédiaire veasy-ca.crt. Conservez ces fichiers dans un répertoire sécurisé avec permissions 600.
Your TAM will provide client.crt and the intermediate CA certificate veasy-ca.crt. Store these files in a secure directory with 600 permissions.
Appel mTLS avec cURL
mTLS call with cURL
curl -X GET https://api.veasyglobal.com/v1/g2/missions \
--cert client.crt \
--key client.key \
--cacert veasy-ca.crt \
-H "X-Org-ID: org_XXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json"
Appel mTLS avec Python (requests)
mTLS call with Python (requests)
import requests
response = requests.get(
"https://api.veasyglobal.com/v1/g2/missions",
cert=("client.crt", "client.key"),
verify="veasy-ca.crt",
headers={
"X-Org-ID": "org_XXXXXXXXXXXXXXXX",
"Content-Type": "application/json",
}
)
response.raise_for_status()
print(response.json())
4. Scopes et permissions
4. Scopes and permissions
Chaque clé API ou certificat client est limité à un ensemble de scopes définis par votre contrat. Tenter d'accéder à une ressource hors scope retourne une erreur 403 Forbidden avec le code SCOPE_INSUFFICIENT.
Each API key or client certificate is restricted to a set of scopes defined by your contract. Attempting to access an out-of-scope resource returns a 403 Forbidden error with code SCOPE_INSUFFICIENT.
Les scopes disponibles sont :
Available scopes are:
g2:read
g2:write
g2:admin
sentinel:read
sentinel:write
guard:cameras
guard:alerts
guard:reporting
5. Rotation des clés et expiration
5. Key rotation and expiry
Les clés API expirent automatiquement après 90 jours. Votre TAM vous enverra un rappel 15 jours avant l'expiration. Pour renouveler :
API keys expire automatically after 90 days. Your TAM will send a reminder 15 days before expiry. To renew:
- Contactez votre TAM ou ouvrez un ticket de priorité P2 dans le portail support
- Contact your TAM or open a P2 priority ticket in the support portal
- Précisez l'identifiant de la clé expirante (disponible dans les logs d'audit)
- Specify the expiring key identifier (available in audit logs)
- La nouvelle clé sera émise avec un délai de chevauchement de 48h pour éviter toute interruption de service
- The new key will be issued with a 48h overlap period to avoid service interruption
Pour les certificats mTLS, la durée de validité est de 12 mois. La procédure de renouvellement est identique à l'émission initiale (nouvelle CSR).
For mTLS certificates, validity is 12 months. The renewal procedure is identical to initial issuance (new CSR required).
Bonne pratique :
Best practice:
Mettez en place une alerte monitoring sur le champ key_expires_at retourné dans les headers de réponse API pour anticiper les expirations dans vos pipelines automatisés.
Set up a monitoring alert on the key_expires_at field returned in API response headers to proactively track expirations in automated pipelines.