Passer au contenu principal
POST
Émettre une attestation
Signe une charge utile en utilisant la clé de signature disponible d’un émetteur et enregistre l’attestation résultante. La politique de l’émetteur, l’état de la clé, l’environnement et les limites d’utilisation peuvent empêcher la frappe.

Choisir un type d’enregistrement

Pour un enregistrement structuré, choisissez schema dans le menu déroulant du type d’enregistrement et entrez un objet JSON dans claims. Laissez payload_b64url vide. Le serveur sérialise ces champs dans la charge utile JSON signée. Cela identifie le type d’enregistrement ; cela n’établit pas indépendamment que les revendications sont vraies.

Choisir un pack de vérification

Les packs de vérification appartiennent à votre espace de travail. Utilisez le sélecteur ci-dessous avec le même environnement et la même clé API que Try it, puis copiez l’ID sélectionné dans pack_id. Omettez ce champ pour un enregistrement autonome. Vous pouvez également utiliser Lister les packs de vérification ou Mint dans Console.

Utiliser une charge utile existante

Si vous avez déjà les octets exacts à signer, omettez schema et claims. Encodez les octets originaux en base64url non paddé dans payload_b64url. Pour JSON, sérialisez d’abord l’objet. Les champs d’application tels que subject, claims et schema appartiennent à ces octets encodés ; utilisez-les soit via l’entrée structurée ci-dessus, soit à l’intérieur des octets encodés, jamais les deux. Ce point de terminaison ne vérifie pas indépendamment la véracité des affirmations soumises ni ne valide des schémas d’informations d’identification arbitraires. Utilisez le kid de la clé et le alg correspondant. L’enregistrement de la clé publique seule ne rend pas une clé de signature privée disponible. Voir clés d’émetteur.

Expiration facultative

Pour les schema et claims structurés, définissez expires_at_unix sur un horodatage Unix futur en secondes. Truthlocks l’inclut à la racine de la charge utile JSON signée. Avec payload_b64url, placez ce champ à l’intérieur de la charge utile JSON exacte avant de l’encoder et omettez le champ de requête séparé. Après cet instant, la vérification renvoie EXPIRED. L’expiration ne peut pas être prolongée ou supprimée d’un enregistrement signé existant ; créez un remplacement. Omettez-la lorsque vous ne souhaitez pas d’expiration d’attestation. Les dates figurant dans les revendications individuelles, telles que le expiry_date d’un passeport, sont des revendications distinctes et ne définissent pas automatiquement l’expiration de l’attestation. Les enregistrements existants ne se voient pas attribuer de date rétroactivement. Conservez la charge utile exacte et l’expiration lors de la nouvelle tentative. Une nouvelle tentative idempotente renvoie l’enregistrement original même après son expiration.

Réessayer en toute sécurité

Idempotency-Key est requis. Générez une valeur par frappe prévue et conservez-la avec la demande originale pour les tentatives. Ne la réutilisez pas pour un contenu différent.

Intégrité des documents

Le hachage du document stocké est sélectionné dans cet ordre :
  1. claims.document.sha256 à l’intérieur d’une charge utile JSON.
  2. Le document_hash de la requête.
  3. SHA-256 des octets de la charge utile décodée.
Un hachage intégré a priorité sur le champ séparé. Incluez le hachage dans la charge utile signée lorsque vous devez lier cette revendication à la signature. Un hachage soumis est une revendication concernant un fichier ; le serveur ne peut pas établir le contenu du fichier à partir du seul hachage. Passez document_hash_hex à vérification pour comparer un hachage de fichier. Conservez la charge utile originale pour la vérification de l’intégrité de la charge utile.

Réponse et livraison

HTTP 201 renvoie attestation_id, issued_at_unix, signature et log. La position du journal est log.leaf_index, et non un log_index de niveau supérieur. recipient_email demande une notification asynchrone. HTTP 201 confirme la frappe, pas la livraison de l’e-mail. Omettez-le lorsque vous distribuez l’enregistrement vous-même. Consultez le guide de démarrage rapide pour une requête utilisant les champs d’entrée et de réponse réels.

Guide des champs de type d’enregistrement

Ces champs sont des structures de revendication suggérées, et non une garantie de validation de revendication ou de vérification d’identité.

Autorisations

X-API-Key
string
header
requis

Clé API pour l'authentification machine-à-machine

En-têtes

Idempotency-Key
string
requis

Conservez la même valeur et le même corps de requête lors de la nouvelle tentative d'une frappe.

Corps

application/json

Choisissez Enregistrement structuré pour sélectionner un type d'enregistrement et saisir des revendications, ou Charge utile encodée pour signer des octets existants. Ne combinez jamais les deux formats d'entrée.

alg
enum<string>
requis

Doit correspondre à la clé de signature de l'émetteur sélectionnée.

Options disponibles:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
issuer_id
string<uuid>
requis

L'UUID de l'émetteur créant l'attestation

Exemple:

"550e8400-e29b-41d4-a716-446655440000"

kid
string
requis

Identifiant de clé pour la clé de signature

Exemple:

"es256-key-1"

schema
enum<string>
requis

Type d'enregistrement pour l'entrée structurée. Fournissez des revendications et omettez payload_b64url. Cette étiquette ne valide pas indépendamment la véracité des revendications.

Options disponibles:
verifiable-id,
passport,
drivers-license,
government-id,
self-sovereign-id,
employment-verification,
professional-role,
membership-card,
professional-certification,
license,
accreditation,
degree,
completion-cert,
course-credit,
transcript,
micro-credential,
training-completion,
medical-license,
dea-registration,
board-certification,
health-credential,
vaccination-record,
aml-kyc,
security-clearance,
sam-gov,
jurisdiction-approval,
attestation-of-will,
bank-verification,
credit-attestation,
income-verification,
skill-badge,
competency,
industry-cert,
product-authenticity,
chain-of-custody,
origin-verification,
custom,
attestation
Exemple:

"verifiable-id"

claims
object
requis

Champs d'enregistrement structurés. Requis avec le schéma ; ne peut pas être combiné avec payload_b64url.

Exemple:
attestation_id
string
content_type
string

Type MIME des octets originaux, tel que application/json, application/pdf ou image/png. L'entrée de schéma/revendications structurée nécessite application/json.

Exemple:

"application/json"

document_hash
string

Hachage SHA-256 hexadécimal optionnel du document. Un claims.document.sha256 intégré a la priorité ; sinon, ce champ est utilisé, puis le hachage de la charge utile décodée.

pack_id
string<uuid>

UUID optionnel du pack de vérification de l'espace de travail. Utilisez la liste des packs de vérification avec la même clé API pour sélectionner un pack actif existant ; omettez pour un enregistrement autonome.

expires_at_unix
integer<int64>

Horodatage Unix futur optionnel en secondes pour l'entrée de schéma/revendications structuré. Il est inclus dans la charge utile JSON signée. Pour l'entrée payload_b64url, omettez ce champ de requête et intégrez plutôt expires_at_unix à la racine de la charge utile JSON exacte. L'expiration ne peut pas être modifiée sur place.

Plage requise: 1 <= x <= 253402300799
recipient_email
string<email>

Destinataire optionnel pour une notification asynchrone après la frappe. Une réponse de frappe réussie ne confirme pas la livraison.

Réponse

Attestation émise

attestation_id
string<uuid>
issuer_id
string<uuid>
version
string
status
string
expires_at_unix
integer<int64> | null

Expiration signée enregistrée en secondes Unix ; null signifie qu'aucune expiration n'est enregistrée. Les enregistrements hérités ne se voient pas attribuer de nouvelle expiration.

issued_at_unix
integer<int64>
payload_hash
string
signature
object
log
object
governance
object | null