Saltar al contenido principal
POST
Atestación de acuñación
Firma una carga útil utilizando la clave de firma disponible de un emisor y registra la atestación resultante. La política del emisor, el estado de la clave, el entorno y los límites de uso pueden impedir la acuñación.

Elegir un tipo de registro

Para un registro estructurado, elija schema del menú desplegable de tipo de registro e introduzca un objeto JSON en claims. Deje payload_b64url vacío. El servidor serializa estos campos en la carga JSON firmada. Esto identifica el tipo de registro; no establece de forma independiente que las afirmaciones sean verdaderas.

Elegir un paquete de verificación

Los paquetes de verificación pertenecen a su espacio de trabajo. Utilice el selector a continuación con el mismo entorno y clave API que Probar, luego copie el ID seleccionado en pack_id. Omita ese campo para un registro independiente. También puede usar Listar paquetes de verificación o Crear en Console.

Usar una carga útil existente

Si ya tiene los bytes exactos para firmar, omita schema y claims. Codifique los bytes originales como base64url sin relleno en payload_b64url. Para JSON, serialice el objeto primero. Los campos de aplicación como subject, claims y schema pertenecen a esos bytes codificados; utilícelos a través de la entrada estructurada anterior o dentro de los bytes codificados, nunca ambos. Este endpoint no verifica de forma independiente la veracidad de las afirmaciones enviadas ni valida esquemas de credenciales arbitrarios. Utilice el kid de la clave y el alg correspondiente. El registro de clave pública por sí solo no hace que una clave de firma privada esté disponible. Consulte claves de emisor.

Caducidad opcional

Para schema y claims estructurados, establezca expires_at_unix en una marca de tiempo Unix futura en segundos. Truthlocks lo incluye en la raíz de la carga JSON firmada. Con payload_b64url, coloque este campo dentro de la carga JSON exacta antes de codificarlo y omita el campo de solicitud separado. Después de ese instante, la verificación devuelve EXPIRED. La caducidad no se puede extender ni eliminar de un registro firmado existente; cree un reemplazo. Omítala cuando no desee una caducidad de atestación. Las fechas dentro de reclamaciones individuales, como el expiry_date de un pasaporte, son reclamaciones separadas y no establecen automáticamente la caducidad de la atestación. A los registros existentes no se les asigna una fecha retrospectivamente. Conserve la carga útil y la caducidad exactas al reintentar. Un reintento idempotente devuelve el registro original incluso después de su caducidad.

Reintentar de forma segura

Idempotency-Key es obligatorio. Genere un valor por acuñación prevista y consérvelo con la solicitud original para reintentos. No lo reutilice para contenido diferente.

Integridad del documento

El hash del documento almacenado se selecciona en este orden:
  1. claims.document.sha256 dentro de una carga útil JSON.
  2. El document_hash de la solicitud.
  3. SHA-256 de los bytes de la carga útil decodificada.
Un hash incrustado tiene prioridad sobre el campo separado. Incluya el hash en la carga útil firmada cuando necesite vincular esa reclamación a la firma. Un hash enviado es una reclamación sobre un archivo; el servidor no puede establecer el contenido del archivo solo a partir del hash. Pase document_hash_hex a verification para comparar un hash de archivo. Conserve la carga útil original para la verificación de la integridad de la carga útil.

Respuesta y entrega

HTTP 201 devuelve attestation_id, issued_at_unix, signature y log. La posición del registro es log.leaf_index, no un log_index de nivel superior. recipient_email solicita notificación asíncrona. HTTP 201 confirma la acuñación, no la entrega del correo electrónico. Omítalo cuando distribuya el registro usted mismo. Consulte el inicio rápido para una solicitud que utiliza los campos de entrada y respuesta reales.

Guía de campos de tipo de registro

Estos campos son estructuras de reclamación sugeridas, no una garantía de validación de reclamación o verificación de identidad.

Autorizaciones

X-API-Key
string
header
requerido

Clave API para autenticación máquina a máquina

Encabezados

Idempotency-Key
string
requerido

Conserve el mismo valor y cuerpo de la solicitud al reintentar una acuñación.

Cuerpo

application/json

Elija Registro estructurado para seleccionar un tipo de registro e ingresar reclamaciones, o Carga útil codificada para firmar bytes existentes. Nunca combine ambos formatos de entrada.

alg
enum<string>
requerido

Debe coincidir con la clave de firma del emisor seleccionada.

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

El UUID del emisor que crea la atestación

Ejemplo:

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

kid
string
requerido

Identificador de clave para la clave de firma

Ejemplo:

"es256-key-1"

schema
enum<string>
requerido

Tipo de registro para entrada estructurada. Proporcione reclamaciones y omita payload_b64url. Esta etiqueta no valida de forma independiente la veracidad de las reclamaciones.

Opciones 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
Ejemplo:

"verifiable-id"

claims
object
requerido

Campos de registro estructurados. Requerido con esquema; no se puede combinar con payload_b64url.

Ejemplo:
attestation_id
string
content_type
string

Tipo MIME de los bytes originales, como application/json, application/pdf o image/png. La entrada de esquema/declaraciones estructuradas requiere application/json.

Ejemplo:

"application/json"

document_hash
string

Hash SHA-256 hexadecimal opcional del documento. Un claims.document.sha256 incrustado tiene prioridad; de lo contrario, se utiliza este campo, luego el hash de la carga decodificada.

pack_id
string<uuid>

UUID opcional del paquete de verificación del espacio de trabajo. Utilice List verification packs con la misma clave API para seleccionar un paquete activo existente; omítalo para un registro independiente.

expires_at_unix
integer<int64>

Marca de tiempo Unix futura opcional en segundos para la entrada de esquema/reclamaciones estructuradas. Se incluye en la carga JSON firmada. Para la entrada payload_b64url, omita este campo de solicitud e incruste expires_at_unix en la raíz de la carga JSON exacta. La caducidad no se puede cambiar en su lugar.

Rango requerido: 1 <= x <= 253402300799
recipient_email
string<email>

Destinatario opcional para notificación asíncrona después de la acuñación. Una respuesta de acuñación exitosa no confirma la entrega.

Respuesta

Atestación acuñada

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

Caducidad firmada registrada en segundos Unix; nulo significa que no se registra ninguna caducidad. A los registros heredados no se les asigna una nueva caducidad.

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