Saltar para o conteúdo principal
POST
Emitir Atestado
Assina uma carga útil usando a chave de assinatura disponível de um emissor e registra a atestação resultante. A política do emissor, o status da chave, o ambiente e os limites de uso podem impedir a cunhagem.

Escolha um tipo de registro

Para um registo estruturado, escolha schema na lista suspensa de tipo de registo e insira um objeto JSON em claims. Deixe payload_b64url vazio. O servidor serializa esses campos no payload JSON assinado. Isso identifica o tipo de registo; não estabelece independentemente que as reivindicações são verdadeiras.

Escolha um pacote de verificação

Os pacotes de verificação pertencem ao seu espaço de trabalho. Use o seletor abaixo com o mesmo ambiente e chave de API de Experimente, então copie o ID selecionado para pack_id. Omita esse campo para um registro autônomo. Você também pode usar Listar pacotes de verificação ou Emitir no Console.

Usar um payload existente

Se você já tiver os bytes exatos para assinar, omita schema e claims. Codifique os bytes originais como base64url sem preenchimento em payload_b64url. Para JSON, serialize o objeto primeiro. Campos de aplicação como subject, claims e schema pertencem a esses bytes codificados; use-os através da entrada estruturada acima ou dentro dos bytes codificados, nunca ambos. Este endpoint não verifica independentemente a veracidade das reivindicações enviadas nem valida esquemas de credenciais arbitrários. Use o kid da chave e o alg correspondente. O registro de chave pública por si só não torna uma chave de assinatura privada disponível. Consulte chaves do emissor.

Validade opcional

Para schema e claims estruturados, defina expires_at_unix para um timestamp Unix futuro em segundos. O Truthlocks inclui-o na raiz do payload JSON assinado. Com payload_b64url, coloque este campo dentro do payload JSON exato antes de codificá-lo e omita o campo de solicitação separado. Após esse instante, a verificação retorna EXPIRED. A expiração não pode ser estendida ou removida de um registro assinado existente; crie um substituto. Omita-a quando não quiser uma expiração de atestado. Datas dentro de reivindicações individuais, como o expiry_date de um passaporte, são reivindicações separadas e não definem automaticamente a expiração do atestado. Registros existentes não recebem uma data retroativamente. Mantenha a carga útil exata e a expiração ao tentar novamente. Uma nova tentativa idempotente retorna o registro original mesmo após sua expiração.

Tentar novamente com segurança

Idempotency-Key é obrigatório. Gere um valor por cunhagem pretendida e mantenha-o com a solicitação original para novas tentativas. Não o reutilize para conteúdo diferente.

Integridade do documento

O hash do documento armazenado é selecionado nesta ordem:
  1. claims.document.sha256 dentro de um payload JSON.
  2. O document_hash da solicitação.
  3. SHA-256 dos bytes do payload decodificado.
Um hash incorporado tem precedência sobre o campo separado. Inclua o hash no payload assinado quando precisar de vincular essa alegação à assinatura. Um hash submetido é uma alegação sobre um ficheiro; o servidor não pode estabelecer o conteúdo do ficheiro apenas a partir do hash. Passe document_hash_hex para verificação para comparar um hash de arquivo. Mantenha o payload original para verificação de integridade do payload.

Resposta e entrega

HTTP 201 retorna attestation_id, issued_at_unix, signature e log. A posição do log é log.leaf_index, não um log_index de nível superior. recipient_email solicita notificação assíncrona. HTTP 201 confirma a cunhagem, não a entrega do e-mail. Omita-o ao distribuir o registro você mesmo. Consulte o início rápido para uma solicitação usando os campos de entrada e resposta reais.

Guia de campo de tipo de registro

Esses campos são estruturas de reivindicação sugeridas, não uma garantia de validação de reivindicação ou verificação de identidade.

Autorizações

X-API-Key
string
header
obrigatório

Chave de API para autenticação máquina a máquina

Cabeçalhos

Idempotency-Key
string
obrigatório

Mantenha o mesmo valor e corpo da solicitação ao tentar novamente uma cunhagem.

Corpo

application/json

Escolha Registro estruturado para selecionar um tipo de registro e inserir reivindicações, ou Payload codificado para assinar bytes existentes. Nunca combine ambos os formatos de entrada.

alg
enum<string>
obrigatório

Deve corresponder à chave de assinatura do emissor selecionada.

Opções disponíveis:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
issuer_id
string<uuid>
obrigatório

O UUID do emissor que cria o atestado

Exemplo:

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

kid
string
obrigatório

Identificador da chave para a chave de assinatura

Exemplo:

"es256-key-1"

schema
enum<string>
obrigatório

Tipo de registro para entrada estruturada. Forneça reivindicações e omita payload_b64url. Este rótulo não valida independentemente a veracidade das reivindicações.

Opções disponíveis:
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
Exemplo:

"verifiable-id"

claims
object
obrigatório

Campos de registro estruturados. Obrigatório com esquema; não pode ser combinado com payload_b64url.

Exemplo:
attestation_id
string
content_type
string

Tipo MIME dos bytes originais, como application/json, application/pdf ou image/png. A entrada de esquema/declarações estruturadas requer application/json.

Exemplo:

"application/json"

document_hash
string

Hash SHA-256 hexadecimal opcional do documento. Um claims.document.sha256 incorporado tem precedência; caso contrário, este campo é usado, depois o hash do payload decodificado.

pack_id
string<uuid>

UUID opcional do pacote de verificação do espaço de trabalho. Use Listar pacotes de verificação com a mesma chave de API para selecionar um pacote ativo existente; omita para um registro autônomo.

expires_at_unix
integer<int64>

Timestamp Unix futuro opcional em segundos para entrada de esquema/declarações estruturadas. Ele é incluído no payload JSON assinado. Para entrada payload_b64url, omita este campo de solicitação e incorpore expires_at_unix na raiz do payload JSON exato. A expiração não pode ser alterada no local.

Intervalo necessário: 1 <= x <= 253402300799
recipient_email
string<email>

Destinatário opcional para notificação assíncrona após a cunhagem. Uma resposta de cunhagem bem-sucedida não confirma a entrega.

Resposta

Atestação cunhada

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

Expiração assinada registrada em segundos Unix; nulo significa que nenhuma expiração é registrada. Registros legados não recebem uma nova expiração.

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