Skip to main contentCertyo Developer Portal

Integration Amazon Web Services

Architecture de reference pour integrer Certyo avec AWS en utilisant EventBridge, Lambda, Step Functions et API Gateway.

EventBridge API Destinations
EventBridge API Destinations supporte le reessai automatique avec backoff exponentiel — configurez un maximum de 185 reessais pour une couverture de 24h.

Prerequis

  • Compte AWS avec des permissions IAM pour EventBridge, Lambda, Step Functions et Secrets Manager
  • AWS CLI v2 configure avec des credentials
  • Cle API Certyo (stockee dans AWS Secrets Manager — voir la section Authentification ci-dessous)
  • Node.js 20+ ou Python 3.12+ (pour le developpement Lambda)

Architecture de reference

Cette architecture exploite le routage d'evenements natif AWS et le calcul serverless pour s'integrer avec Certyo :

AWS Reference Architecture
Source System ──► EventBridge ──► API Destination (Certyo) ──► POST /api/v1/records
                          │                                           │
                     DLQ (SQS)                                  Step Functions
                   for failed                               (verification workflow)
                    deliveries                                        │
                                                              ┌──────┴──────┐
                                                              │  Wait 90s   │
                                                              │  Verify     │
                                                              │  Branch     │
                                                              └──────┬──────┘
                                                                     │
                                                              SNS notification
                                                           (anchored / failed)

EventBridge recoit les evenements de domaine de vos systemes sources (S3, DynamoDB Streams, applications personnalisees). Pour le transfert simple, API Destinations appelle Certyo directement sans intermediaire Lambda. Pour les transformations complexes, Lambda traite les evenements avant l'ingestion. Step Functions orchestrent les workflows de verification multi-etapes.

EventBridge API Destinations

Le modele d'integration le plus simple : EventBridge appelle directement l'API Certyo via une API Destination. Aucun code Lambda requis pour le transfert direct d'evenements.

Comment ca fonctionne

  • Connection — Stocke la cle API Certyo avec le type d'authentification API_KEY . EventBridge gere la rotation des credentials si vous mettez a jour le secret.
  • API Destination — Definit l'URL de l'endpoint Certyo, la methode HTTP et la limite de debit d'invocation.
  • Rule — Correspond aux evenements entrants par source, detail-type ou modeles personnalises et les route vers l'API Destination.
  • Input Transformer — Mappe votre schema d'evenement vers le payload d'enregistrement Certyo sans code Lambda.
  • Retry + DLQ — Reessai integre avec backoff exponentiel (jusqu'a 24 heures avec 185 reessais). Les evenements echoues arrivent dans une file SQS de dead-letter.

Lambda Functions

Pour les evenements necessitant une transformation, un enrichissement ou une logique conditionnelle avant l'ingestion, utilisez Lambda comme couche de traitement :

  • Declencheur S3 — De nouveaux objets dans un bucket declenchent une Lambda qui lit le fichier, extrait les enregistrements et envoie chacun a Certyo
  • DynamoDB Streams — Capturez les donnees de changement des tables DynamoDB et transmettez les elements modifies comme enregistrements Certyo
  • Gestionnaire de Webhook — Recevez des webhooks de systemes tiers via API Gateway, transformez et ingerez

Step Functions

Orchestrez des workflows multi-etapes qui ingerent un enregistrement, attendent l'ancrage, verifient le resultat et bifurquent en succes ou echec :

  • Standard Workflow — Pour les flux de verification longue duree (jusqu'a 1 an d'execution). Utilise des etats Wait pour faire une pause pendant la fenetre d'ancrage de ~60-90 secondes de Certyo.
  • Express Workflow — Pour les executions a haut volume et courte duree (jusqu'a 5 minutes). Ideal pour l'ingestion en masse ou la verification est geree separement.

API Gateway

Placez Certyo devant les consommateurs internes avec API Gateway pour les plans d'utilisation, la limitation et la gestion des cles API :

  • Creez un proxy REST API qui transmet les requetes a https://www.certyos.com/api/v1/
  • Ajoutez un plan d'utilisation avec limitation (par exemple, 100 requetes/seconde par consommateur) et des quotas mensuels
  • Injectez le X-API-Key Certyo via un autoriseur Lambda ou un template de mapping VTL
  • Les consommateurs internes s'authentifient avec leurs propres cles API Gateway — ils ne voient jamais la cle Certyo

Exemples de code

certyo_s3_ingest.pypython
import json
import os
import urllib.parse
import boto3
import urllib3

secrets_client = boto3.client("secretsmanager")
s3_client = boto3.client("s3")
http = urllib3.PoolManager()

CERTYO_API_URL = os.environ.get("CERTYO_API_URL", "https://www.certyos.com")
CERTYO_TENANT_ID = os.environ["CERTYO_TENANT_ID"]
SECRET_ARN = os.environ["CERTYO_SECRET_ARN"]

_api_key_cache = None


def get_api_key():
    global _api_key_cache
    if _api_key_cache is None:
        secret = secrets_client.get_secret_value(SecretId=SECRET_ARN)
        _api_key_cache = json.loads(secret["SecretString"])["apiKey"]
    return _api_key_cache


def handler(event, context):
    """
    Triggered by S3 PutObject events. Reads the uploaded JSON file,
    extracts records, and sends each to Certyo for blockchain anchoring.
    """
    api_key = get_api_key()
    results = []

    for record in event["Records"]:
        bucket = record["s3"]["bucket"]["name"]
        key = urllib.parse.unquote_plus(record["s3"]["object"]["key"])

        print(f"Processing s3://{bucket}/{key}")

        # Read the S3 object
        obj = s3_client.get_object(Bucket=bucket, Key=key)
        body = json.loads(obj["Body"].read().decode("utf-8"))

        # Support single record or array of records
        items = body if isinstance(body, list) else [body]

        for item in items:
            record_id = item.get("id", key.split("/")[-1].replace(".json", ""))

            payload = {
                "tenantId": CERTYO_TENANT_ID,
                "database": f"s3-{bucket}",
                "collection": key.rsplit("/", 1)[0] if "/" in key else "root",
                "recordId": record_id,
                "recordVersion": str(item.get("version", "1")),
                "operationType": "upsert",
                "recordPayload": item,
                "sourceTimestamp": record["eventTime"],
                "idempotencyKey": f"{record_id}-{record['eventTime'][:10]}",
            }

            response = http.request(
                "POST",
                f"{CERTYO_API_URL}/api/v1/records",
                body=json.dumps(payload),
                headers={
                    "X-API-Key": api_key,
                    "Content-Type": "application/json",
                },
            )

            result = json.loads(response.data.decode("utf-8"))

            if response.status != 202:
                print(f"ERROR: Certyo returned {response.status} for {record_id}: {result}")
                raise Exception(f"Ingestion failed for {record_id}: {response.status}")

            print(f"Record {record_id} accepted. Hash: {result['recordHash']}")
            results.append(result)

    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": f"Ingested {len(results)} records",
            "records": results,
        }),
    }

Authentification

Le modele d'authentification recommande utilise la gestion native des secrets AWS avec IAM pour l'autorisation de service a service :

  • Secrets Manager — Stockez le X-API-Key Certyo comme un secret. Activez la rotation automatique si votre organisation l'exige.
  • EventBridge Connection — L'objet de connexion stocke en securite la cle API et l'injecte dans chaque requete d'API Destination. Vous ne gerez pas la cle dans le code applicatif.
  • Role d'execution Lambda — Accordez aux fonctions Lambda secretsmanager:GetSecretValue sur l'ARN specifique du secret. Utilisez le principe du moindre privilege.
  • Cles API Gateway — Pour les consommateurs internes, emettez des cles API Gateway liees aux plans d'utilisation. La passerelle injecte la cle Certyo via un autoriseur Lambda ou un template de mapping.
IAM policy for Lambda to read Certyo secretjson
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadCertyoApiKey",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:certyo/api-key-*"
    }
  ]
}

Optimisation des couts

Choisissez le bon modele d'integration en fonction de votre charge de travail pour minimiser les couts AWS :

  • EventBridge API Destinations (le moins cher) — Pas de couts d'invocation Lambda. Vous ne payez que pour les evenements EventBridge (1,00 $ par million d'evenements) et les invocations d'API Destination. Utilisez ceci pour le transfert simple d'evenements sans transformation.
  • EventBridge + Input Transformer — Si vous avez seulement besoin de remodeler le payload de l'evenement (renommer des champs, extraire des valeurs imbriquees), utilisez l'Input Transformer d'EventBridge au lieu de Lambda. Zero cout de calcul.
  • Lambda (pour les transformations) — Reservez Lambda pour les cas ou vous devez lire depuis S3, appeler des API externes ou appliquer une logique metier complexe avant l'ingestion. Utilisez ARM64 (Graviton) pour 20 % d'economie.
  • Step Functions Express — Pour les workflows de verification a haut volume (>100K executions/mois), les Express Workflows coutent jusqu'a 80 % de moins que les Standard Workflows.
Conseil
Pour la plupart des integrations, EventBridge API Destinations avec Input Transformers gere tout sans une seule ligne de code Lambda. Commencez par la et ajoutez Lambda uniquement quand vous en avez besoin.

Prochaines etapes

  • Deployez le stack CDK ci-dessus pour provisionner le pipeline EventBridge complet en quelques minutes
  • Publiez un evenement de test sur le bus domain-events et verifiez qu'il arrive dans Certyo
  • Deployez le workflow de verification Step Functions pour une confirmation d'ancrage de bout en bout
  • Consultez le Guide d'ingestion pour les details sur le schema d'enregistrement et l'idempotence
  • Voir le Guide de verification pour les details sur les preuves cryptographiques
AI Integration · v1.0.0

AI Integration Skill

Download a skill file that enables AI agents to generate working AWS + Certyo integration code for any language or framework.

v1.0.0
What is this?
A markdown file containing AWS-specific field mappings, authentication setup, code examples, and integration patterns for Certyo. Drop it into your AI agent's context and ask it to generate integration code.

What's inside

  • Authentification — EventBridge Connection avec API Key, Lambda avec Secrets Manager
  • Architecture — EventBridge → API Destination ou Lambda → Certyo → Step Functions verification
  • Exemples de code — Python Lambda, stack CDK TypeScript, workflow Step Functions ASL
  • API Destinations — Transfert direct vers Certyo sans Lambda avec politiques de reessai
  • Step Functions — Workflow de verification avec etats Wait, boucles de reessai et branchement
  • Optimisation des couts — Comparaison API Destinations vs Lambda vs Express Workflows

How to use

Claude Code

Place the file in your project's .claude/commands/ directory, then use it as a slash command:

# Download the skill file
mkdir -p .claude/commands
curl -o .claude/commands/certyo-aws.md \
  https://www.certyos.com/developers/skills/certyo-aws-skill.md

# Use it in Claude Code
/certyo-aws "Generez une API Destination EventBridge qui transmet les evenements a Certyo"

Cursor / Copilot / Any AI Agent

Add the file to your project root or attach it to a conversation. The AI agent will use the AWS-specific patterns, field mappings, and code examples to generate correct integration code.

# Add to your project
curl -o CERTYO_AWS.md \
  https://www.certyos.com/developers/skills/certyo-aws-skill.md

# Then in your AI agent:
"Using the Certyo AWS spec in CERTYO_AWS.md,
 generez une api destination eventbridge qui transmet les evenements a certyo"

CLAUDE.md Context File

Append the skill file to your project's CLAUDE.md so every Claude conversation has AWS + Certyo context automatically.

# Append to your project's CLAUDE.md
echo "" >> CLAUDE.md
echo "## Certyo AWS Integration" >> CLAUDE.md
cat CERTYO_AWS.md >> CLAUDE.md