Documentação para programadores do Dazr Identity

As pessoas já podem usar a sua conta Google ou Microsoft dentro do Dazr Identity, pelo que a sua aplicação não precisa de botões Google e Microsoft separados ao lado: um botão em vez de três.

Descoberta e endpoints

Tudo está descrito no documento de descoberta. Aponte a sua biblioteca para o emissor e ela encontra o resto.

O quêEndereço
Emissorhttps://identity.dazr.eu
Discoveryhttps://identity.dazr.eu/.well-known/openid-configuration
Autorizaçãohttps://identity.dazr.eu/oauth/authorize
Tokenhttps://identity.dazr.eu/oauth/token
Informações do utilizadorhttps://identity.dazr.eu/oauth/userinfo
Chaves públicas (JWKS)https://identity.dazr.eu/oauth/jwks
Revogação (RFC 7009)https://identity.dazr.eu/oauth/revoke
Introspeção (RFC 7662), só aplicações de servidor webhttps://identity.dazr.eu/oauth/introspect
Terminar sessão (logout iniciado pela RP)https://identity.dazr.eu/oauth/logout
Relatórios de verificação, só aplicações de servidor webhttps://identity.dazr.eu/oauth/verification-report

Registar uma aplicação

Uma aplicação na consola de programadores do Dazr Identity: ID de cliente, URL de descoberta, URIs de redirecionamento, âmbitos e os passos para a ligar

Guias de integração

Cada stack abaixo usa o seu próprio suporte padrão de OpenID Connect. Precisa de três valores da consola: o ID de cliente, o segredo de cliente (só aplicações de servidor web) e o URI de redirecionamento que registou. O resto vem do documento de descoberta.

Qualquer biblioteca OpenID Connect

Se a sua stack não estiver na lista, qualquer cliente OpenID Connect funciona. Verifique estas definições:

O fluxo

  1. Crie um code_verifier aleatório (43 a 128 caracteres) e o respetivo code_challenge = base64url(SHA-256(verifier)). Crie um state e um nonce aleatórios. Guarde os três na sessão do utilizador.
  2. Redirecione para o endpoint de autorização com response_type=code, client_id, redirect_uri, scope (incluindo sempre openid), state, nonce, code_challenge e code_challenge_method=S256.
  3. A pessoa inicia sessão se necessário e vê o ecrã de consentimento com os dados reais. Quando autoriza, volta ao seu URI de redirecionamento com code, state e iss. Verifique se o state corresponde e se iss é https://identity.dazr.eu.
  4. No seu servidor, faça um POST para o endpoint de token com grant_type=authorization_code, code, o mesmo redirect_uri e o code_verifier.
  5. Verifique o token de ID: assinatura ES256 com uma chave do JWKS (corresponda o kid), iss, aud = o seu ID de cliente, exp e o seu nonce. Use sub como chave da conta.
O ecrã de consentimento do Dazr Identity para uma aplicação chamada Ledgerline: indica o nome, o endereço de e-mail e a organização verificada que o utilizador escolheu partilhar

O parâmetro prompt aceita none (responde de imediato com login_required ou consent_required se a pessoa tiver de agir), login (pede à pessoa que volte a iniciar sessão) e consent (mostra o ecrã de consentimento mesmo que já tenha sido aprovado). max_age é suportado. Consentimento memorizado: se a pessoa já aprovou os mesmos âmbitos, volta diretamente à sua aplicação. Se pedir mais depois, o ecrã de consentimento mostra apenas o que é novo.

Âmbitos e claims

Peça apenas aquilo de que precisa. Nada fora desta tabela existe: sem contactos, sem palavras-passe. Os ficheiros só se leem através da API do Dazr Files, com o seu próprio scope files.read.

ScopeClaims
openid (obrigatório)sub: um ID aleatório para a pessoa, igual para todas as aplicações da sua organização e diferente para qualquer outra organização
profilename (se definido) e locale
emailemail e email_verified (sempre true)
addressaddress (formatted, street_address, locality, region, postal_code, country), só se a pessoa tiver guardado uma morada
organisationsorganisations: as organizações que a pessoa assinala no ecrã de consentimento, cada uma com id, name, display_name, website, country, register_number, vat, vat_verified (true apenas quando o serviço VIES da UE confirmou o número de IVA), verified, verification (ver Organizações verificadas) e role (owner, admin ou member)
offline_accessnenhuma claim; recebe também um refresh token

As claims aparecem no token de ID para os âmbitos que a pessoa aprovou. O endpoint de informações do utilizador devolve o mesmo conjunto, com os valores atuais.

Organizações verificadas

O Dazr só verifica uma organização quando fontes oficiais provam duas coisas: quem é a pessoa e que representa esta organização, com o seu nome, número de registo e número de IVA. Normalmente, o administrador assina uma breve declaração com uma assinatura eletrónica qualificada (QES) e junta a certidão do registo comercial em que consta; com uma certidão selada pelo registo, como uma visura camerale italiana ou um extrato KVK neerlandês, é imediato; caso contrário, o Dazr analisa-a. Uma assinatura qualificada, por si só, nunca torna uma organização verificada. Cada organização na claim organisations traz a sua verificação atual:

Verificar uma organização no Dazr Identity: o administrador assina a declaração com uma assinatura qualificada já ou mais tarde por e-mail, ou carrega a certidão da empresa e um documento de identificação
verification.statusSignificado
unverifiedNão verificada, ou uma verificação falhou, expirou ou foi revogada (por exemplo, depois de mudar a denominação ou o número de registo).
pendingA verificação está em curso: foi pedido ao representante que assinasse, a certidão do registo comercial ainda falta ou o Dazr está a analisar documentos. method indica a via iniciada, por exemplo qes (o representante assina a declaração), qseal, pec, letter, video ou documents.
verifiedVerificada. method é qes_org (assinatura qualificada, o certificado indica a organização), extract_sealed (assinatura qualificada ou documento de identificação analisado, mais uma certidão selada pelo registo comercial), qes_reviewed (assinatura qualificada, certidão verificada pelo Dazr), qseal (o selo eletrónico qualificado da organização), documents, pec (um código enviado para o endereço de e-mail certificado da organização, PEC, Itália), letter (um código enviado por correio para a sede), video (uma videochamada com o Dazr) ou extract. authority indica o que provou que a pessoa representa a organização (ver abaixo), e verified_at é uma hora Unix.

Apenas quando o estado é verified, verification.authority (e authority nos webhooks) indica como foi provada a ligação entre a pessoa e a organização. Cada verificação é uma prova documentada, verificada uma vez na data indicada. Não garante a solvência nem a conduta da organização e não mostra a quem pertence a organização.

verification.authorityO que prova
certificateProva documentada de que o pedido foi assinado com uma assinatura eletrónica qualificada, ou selado com um selo eletrónico qualificado, cujo certificado indica a organização e o seu número de registo. A Dazr verificou o certificado nas listas de confiança da UE e a sua revogação.
register_extractProva documentada de que um administrador ou representante legal confirmou o pedido, com uma assinatura eletrónica qualificada ou um documento de identificação verificado pela Dazr, e de que uma certidão selada pelo registo comercial, com 3 meses no máximo, o indica.
reviewedProva documentada de que um administrador ou representante legal confirmou o pedido, com uma assinatura eletrónica qualificada ou um documento de identificação, e de que uma pessoa da Dazr verificou uma certidão do registo, com 3 meses no máximo, que o indica.
pecProva documentada de que alguém com acesso ao endereço de e-mail certificado da organização (PEC, Itália), tal como consta do registo comercial, confirmou o pedido com um código de utilização única.
letterProva documentada de que alguém com acesso ao correio da sede confirmou o pedido com um código de utilização única que a Dazr enviou para lá por carta.
videoProva documentada de que uma pessoa da Dazr viu, numa videochamada, o documento de identificação da pessoa que confirmou o pedido e uma certidão oficial que a indica como administradora ou representante legal.

As mesmas definições estão nos termos de utilização, na secção 7 dos Termos para Programadores e em cada relatório de verificação.

O booleano verified mantém-se por compatibilidade e é igual a verification.status === 'verified'. Cada organização tem também um id, o mesmo usado pelos webhooks.

Quando o estado é pending ou verified, verification.report_url é o endereço do respetivo relatório de verificação.

"organisations": [{
  "id": "org_3k9x2m0q8w1v5t7a", "name": "Conti Logistica S.r.l.", "country": "IT",
  "register_number": "REA MI1234567", "vat": "IT12345678903", "vat_verified": true,
  "display_name": "Conti", "website": "https://conti.example",
  "verified": false, "verification": { "status": "pending", "method": "qes" }, "role": "owner"
}]

role e a pertença são lidas de novo em cada renovação de token e pedido de informações do utilizador: após uma mudança de função, a resposta seguinte traz a nova função, e uma organização que a pessoa deixou ou da qual foi removida deixa de ser incluída. Quando um administrador da organização desliga a sua aplicação, a organização é omitida dos tokens emitidos antes, até um membro a voltar a partilhar com a sua aplicação num novo início de sessão. display_name e website são null quando a organização não os definiu; name é sempre a denominação legal.

Países e prazos

Podem verificar-se organizações dos 27 países da UE, Noruega, Islândia, Liechtenstein, Suíça e Reino Unido. A via mais rápida depende do país:

PaísVerificação de organizaçõesVerificação empresarial
ItáliaImediata com uma assinatura qualificada e uma visura selada pelo registo comercial, ou em poucos minutos com um código para o endereço de e-mail certificado (PEC) da empresaUma visura com 3 meses no máximo, verificada por uma pessoa da Dazr, normalmente num dia útil
Países BaixosImediata com uma assinatura qualificada e uma certidão KVK certificada digitalmenteA partir do registo KVK, verificado por uma pessoa da Dazr, normalmente num dia útil
Áustria, BélgicaImediata com uma assinatura qualificada e uma certidão selada pelo registo comercialUma certidão oficial com 3 meses no máximo, verificada por uma pessoa da Dazr, normalmente num dia útil
Noruega, Dinamarca, Finlândia, França, Polónia, ChéquiaImediata com uma assinatura qualificada cujo certificado indica a organização; caso contrário, uma certidão e um documento, verificados por uma pessoa da Dazr, normalmente num dia útilA partir do registo comercial online, verificado por uma pessoa da Dazr, normalmente num dia útil
Reino UnidoUma certidão e um documento, verificados por uma pessoa da Dazr, normalmente num dia útilA partir da Companies House, verificado por uma pessoa da Dazr, normalmente num dia útil
Todos os outros países suportadosImediata com uma assinatura qualificada cujo certificado indica a organização; caso contrário, uma certidão e um documento, verificados por uma pessoa da Dazr, normalmente num dia útilUma certidão oficial com 3 meses no máximo, verificada por uma pessoa da Dazr, normalmente num dia útil
Em todo o ladoUm código por correio (100 € sem IVA, 3 a 10 dias úteis) ou uma videochamada (200 € sem IVA)Uma videochamada (200 € sem IVA) quando o representante não tem câmara no telemóvel

Os prazos são habituais, não garantidos. Automática significa que regras documentadas decidem quando todas as verificações são claras; quando uma não o é, uma pessoa da Dazr analisa, normalmente num dia útil. A página de ajuda para quem tem de se verificar indica que certidão do registo obter em cada país.

Exigir uma organização verificada

Na consola, defina Exigir uma organização verificada como Verificação iniciada ou Verificada, ou peça-o por pedido com acr_values=urn:dazr:org:verification-started ou acr_values=urn:dazr:org:verified (prevalece o mais rigoroso dos dois). A sua aplicação tem também de pedir o âmbito organisations.

A definição Exigir uma organização verificada na consola de programadores: não exigida, verificação iniciada ou verificada

Quem não tem uma organização que cumpra o requisito é conduzido pelo processo no mesmo início de sessão: o nome, a organização (com o número de IVA verificado no VIES) e depois a verificação. Pode assinar de imediato, receber a declaração por e-mail ou indicar outra pessoa que assine. Depois assinala a organização no ecrã de consentimento (só se podem assinalar organizações que cumpram o requisito) e volta ao seu URI de redirecionamento.

Se outra pessoa ainda tiver de assinar, a pessoa volta com o estado pending, mesmo que tenha pedido Verificada: recebe um código, a claim indica pending e o acr do token de ID é urn:dazr:org:verification-started em vez de urn:dazr:org:verified. Decida sempre com base em verification.status, nunca no facto de o início de sessão ter sido bem-sucedido. Com prompt=none recebe interaction_required quando o requisito não é cumprido.

As alterações à definição aplicam-se a partir do próximo início de sessão. As pessoas com sessão já iniciada não são desligadas: as respostas de renovação, o endpoint de informações do utilizador e os webhooks trazem sempre o estado atual, por isso use-os para reagir nas sessões existentes.

Webhooks

Adicione um URL de webhook (https) na consola. Vê o segredo de assinatura uma vez; pode rodá-lo. O Dazr envia organisation.verification.updated quando uma organização que um dos seus utilizadores partilhou com a sua aplicação passa a pendente, verificada, falhada ou não verificada. As aplicações que nunca receberam uma organização através de consentimento nunca são notificadas.

POST /your/webhook
Content-Type: application/json
Dazr-Event: organisation.verification.updated
Dazr-Delivery: dlv_8Fq2…
Dazr-Signature: t=1791021600,v1=5e0c…

{ "id": "evt_…", "type": "organisation.verification.updated", "created": 1791021600,
  "data": { "organisation": { "id": "org_3k9x2m0q8w1v5t7a", "name": "Conti Logistica S.r.l.", "country": "IT" },
            "status": "verified", "method": "qes_org", "authority": "certificate", "verified_at": 1791021598,
            "report_url": "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a",
            "subjects": ["Xo1c…"] } }

status é pending, verified, failed ou unverified. subjects são os valores sub, na sua aplicação, das pessoas que partilharam esta organização com ela. Verifique a assinatura antes de confiar no corpo:

import crypto from 'node:crypto';
// raw = the request body exactly as received (a string), header = the Dazr-Signature header
function verifyDazrSignature(raw, header, secret) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // reject old deliveries
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + raw).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

Responda com qualquer 2xx em 8 segundos. Caso contrário, o Dazr tenta de novo após cerca de 5 minutos, 30 minutos, 2, 6, 12 e 24 horas e depois marca a entrega como falhada. Todas as tentativas têm o mesmo ID Dazr-Delivery, por isso ignore duplicados. A consola mostra as entregas recentes, pode reenviar uma e pode enviar um evento de teste (webhook.test). Consultar periodicamente o endpoint de informações do utilizador também funciona.

Organizações e funções na sua aplicação

Num portal para clientes empresariais, associe cada organização da Dazr a uma conta de cliente (um tenant) na sua aplicação, e a função da pessoa nessa organização a uma função na sua aplicação.

  1. Peça o âmbito organisations. Cada organização que a pessoa assinala chega com o seu id, role (owner, admin ou member) e verification.
  2. Use organisations[].id como chave do tenant, nunca o nome nem o número de IVA: podem mudar.
  3. Associe a função, por exemplo owner e admin à sua função de administrador e member à sua função de utilizador. Leia-a de novo em cada início de sessão e renovação do token: as funções mudam e as pessoas saem.
  4. Desbloqueie as funcionalidades empresariais apenas quando verification.status for verified, ou kyb.status for approved onde precisar da verificação empresarial.
// claims: the ID token claims or the user info response
const ROLE = { owner: 'tenant_admin', admin: 'tenant_admin', member: 'tenant_user' };

const memberships = (claims.organisations || []).map((o) => ({
  tenantId: o.id,                              // e.g. org_3k9x2m0q8w1v5t7a
  role: ROLE[o.role] || 'tenant_user',
  verified: o.verification?.status === 'verified',
  businessVerified: o.kyb?.status === 'approved',
}));

Com o Keycloak

Quando o Keycloak faz de broker do Dazr Identity (veja o guia do Keycloak), adicione mappers no separador Mappers do fornecedor de identidade, com o sync mode Force. O Keycloak lê estes caminhos na resposta de user info, e um caminho pode indicar uma posição numa lista: organisations[0] é a primeira organização que a pessoa assinalou. Para um portal com uma conta de cliente por pessoa, isso chega; se houver pessoas que trabalham para várias organizações, peça-lhes que assinalem apenas uma, ou leia a lista completa na sua aplicação.

Tipo de mapperClaimResultado
Attribute Importerorganisations[0].idAtributo de utilizador dazr_org_id: a chave do tenant
Attribute Importerorganisations[0].nameAtributo de utilizador dazr_org_name
Claim to Roleorganisations[0].role, valor da claim ownerFunção de realm ou de cliente tenant_admin
Claim to Roleorganisations[0].role, valor da claim adminFunção de realm ou de cliente tenant_admin
Claim to Roleorganisations[0].role, valor da claim memberFunção de realm ou de cliente tenant_user
Claim to Roleorganisations[0].verification.status, valor da claim verifiedFunção verified_business

Depois adicione um mapper User Attribute para dazr_org_id ao client scope da sua aplicação no Keycloak, para que a sua aplicação receba a chave do tenant nos tokens do próprio Keycloak, ao lado das funções.

Verificação empresarial (KYB)

A verificação empresarial, muitas vezes chamada KYB (know your business), é o nível de garantia superior, acima da verificação da organização. Acrescenta o registo comercial, uma verificação do documento com selfie em direto para a pessoa que atua pela empresa (o representante), e a verificação da empresa e do representante em listas de sanções e de pessoas politicamente expostas (PEP). Os beneficiários efetivos não fazem parte dela.

Custa 25 € sem IVA por organização, uma única vez. Paga a organização, ou a sua aplicação paga pelos seus clientes com crédito pré-pago. Se parar antes de algum documento ser verificado, o pagamento é reembolsado na totalidade.

Verificação empresarial no Dazr Identity num computador: passo 3 de 5, um código QR grande para tirar as fotografias com o telemóvel, as duas fotografias que se seguem e o estado do telemóvel em direto
  1. Dados da empresa. A forma jurídica, e o número de registo e a sede a partir dos dados legais da organização, confirmados por quem a inicia.
  2. Pagamento. 25 € sem IVA através da Mollie, com fatura na página da organização. Quando a sua aplicação paga com o seu crédito pré-pago, a organização salta este passo.
  3. Documento e selfie. Quem inicia a verificação é administrador ou representante legal, ou indica um, que recebe por e-mail uma ligação com um código de utilização única (válida 14 dias, lembretes ao fim de 2 e 7 dias), confirma a sua função e pode adicionar uma procuração. O representante tira uma fotografia a um passaporte (a página com a fotografia), cartão de cidadão ou autorização de residência (a frente) e uma selfie de frente, em direto com a câmara da página; não é possível carregar nada. Um modelo de IA lê o documento; a Dazr verifica as datas e o nome e, num passaporte, a zona de leitura ótica (dígitos de controlo ICAO 9303). Uma pessoa revisora da Dazr compara a selfie com a fotografia do documento. Num computador, o passo mostra um código QR que passa a captura para um telemóvel, e o computador avança sozinho. Sem câmara no telemóvel, o representante pode marcar uma videochamada com a Dazr (200 € sem IVA, reembolso total se a Dazr cancelar ou não oferecer nenhuma hora).
  4. Verificação no registo comercial. Nome, estado e administradores a partir do registo oficial quando está online (Noruega, Dinamarca, Finlândia, França, Países Baixos, Polónia, Chéquia e Reino Unido), caso contrário a partir de uma certidão oficial com 3 meses no máximo, que a Dazr lê automaticamente.
  5. Verificações de sanções e PEP. A empresa e o representante, confrontados com as listas de sanções da UE, da ONU e da OFAC e com pessoas politicamente expostas. Se a base de dados PEP não estiver disponível, uma pesquisa apenas do nome na Wikidata dá uma indicação. O resultado PEP consta do claim e do relatório e nunca impede a aprovação.
  6. Decisão. Uma pessoa revisora da Dazr compara a selfie com a fotografia do documento e decide, com os resultados das regras de risco documentadas: mostram quando a verificação do documento falha, um nome consta de uma lista de sanções, o registo não indica o representante ou a empresa não é confirmada. Pode aprovar, rejeitar com um motivo, pedir mais informações à organização ou repetir uma verificação, normalmente num dia útil. Os casos de risco elevado precisam de duas pessoas revisoras. Nenhum caso é rejeitado automaticamente.

As organizações aprovadas são novamente confrontadas com as listas de sanções todos os dias e com o estatuto PEP a cada 30 dias. Uma nova correspondência com uma lista de sanções devolve a verificação à análise; uma nova correspondência PEP é assinalada e a verificação continua aprovada. Em ambos os casos, a sua aplicação é avisada.

Uma verificação empresarial aprovada é uma prova documentada de que um administrador ou representante legal, cujo documento de identificação e selfie em direto foram verificados, confirmou o pedido, de que o registo comercial ou uma certidão oficial com 3 meses no máximo mostra a empresa, e de que a empresa e essa pessoa foram confrontadas com listas de sanções e de pessoas politicamente expostas. Os beneficiários efetivos não são verificados.

A claim kyb

Cada organização na claim organisations contém kyb, e verification.assurance_level resume os dois níveis: none, basic (organização verificada) ou kyb (verificação empresarial aprovada).

kyb.statusSignificado
noneSem verificação empresarial, ou a última foi cancelada ou expirou.
in_progressIniciada: a organização está a concluir os passos.
in_reviewEnviada e em análise pela Dazr, ou novamente em análise após uma nova correspondência na triagem.
approvedAprovada. Só então a claim contém verified_claims.
rejectedNão aprovada. A organização pode iniciar uma nova.

Depois da aprovação, verified_claims segue o formato OpenID Connect for Identity Assurance:

"kyb": {
  "status": "approved",
  "report_url": "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a",
  "verified_claims": {
    "verification": {
      "trust_framework": "dazr_kyb", "assurance_level": "kyb", "time": "2026-10-06T09:14:03.000Z",
      "verification_process": "kyb_7Tq2…",
      "evidence": [
        { "type": "electronic_record", "check_details": [{ "check_method": "data", "organization": "no-brreg" }] },
        { "type": "document", "check_details": [{ "check_method": "vpip" }, { "check_method": "pvr" }],
          "note": "ID document and a live, front-facing selfie of the representative; beneficial owners are not part of this verification" }
      ]
    },
    "claims": {
      "legal_name": "Fjordline Logistikk AS", "country": "NO", "registration_number": "912345678",
      "beneficial_owners": "not_verified",
      "started_by_representative": false,
      "screening": { "result": "no_match_found", "pep_checked": true, "last_screened_at": "2026-10-06T03:23:00.000Z" },
      "risk_level": "low"
    }
  }
}

beneficial_owners é sempre not_verified: a verificação empresarial abrange a empresa e a pessoa que atua por ela, não quem a detém. started_by_representative indica se quem a iniciou é também o representante cujo documento foi verificado, ou se o convidou por e-mail. O claim nunca contém nomes, datas de nascimento nem dados de documentos. Ficam no relatório de auditoria, que a sua app pode obter para as organizações partilhadas com ela.

Exigir a verificação empresarial

Na consola, defina Exigir uma organização verificada como Verificação empresarial (KYB), ou peça-a por pedido com acr_values=urn:dazr:org:kyb. Quem ainda não a tiver passa por todos os passos no mesmo início de sessão, um ecrã de cada vez, e continua para a sua app logo que a Dazr a aprove; até lá recebe um e-mail quando for aprovada e inicia sessão novamente. O acr do token de ID só é urn:dazr:org:kyb depois de uma organização ser aprovada, por isso verifique sempre kyb.status === 'approved' antes de desbloquear algo que a exija.

Webhooks para a verificação empresarial

O mesmo evento organisation.verification.updated é enviado quando o estado da verificação empresarial muda, também após uma nova triagem. Os seus dados acrescentam:

"kyb": { "status": "approved", "approved_at": 1791021598, "risk_level": "low" },
"assurance_level": "kyb"

A verificação empresarial por si só

Uma organização também pode iniciar a verificação empresarial por conta própria, em https://identity.dazr.eu/verify/business?org=…, com uma ligação a partir da página dela no Dazr Identity, sem que nenhuma app a peça. O resultado é o mesmo: uma verificação por organização, em que pode confiar cada app com que ela partilha a organização. As imagens de documentos de identificação e selfies são apagadas 30 dias após a decisão; os resultados e o relatório são guardados 5 anos após o fim da verificação, como exigem as regras contra o branqueamento de capitais.

Como é tomada a decisão

Uma pessoa revisora da Dazr decide cada verificação empresarial, normalmente num dia útil, e compara a selfie com a fotografia do documento. Analisa com mais atenção quando se verifica um destes casos:

Tudo o resto é registado e nunca bloqueia a aprovação. Uma possível pessoa politicamente exposta (PEP) é assinalada como screening.pep possible_match no claim e no relatório; se a base de dados PEP não estiver disponível, indica indication_only ou not_screened. Quando o registo não indica administradores, authority é declared_by_representative. Decida se precisa de diligência reforçada.

Países sem registo online

Em países sem registo em tempo real, como Itália, Alemanha, Espanha ou Bélgica, a organização carrega uma certidão oficial (uma visura camerale, um Handelsregisterauszug, uma nota simple). A Dazr lê-a automaticamente e verifica a denominação, o número de registo, a data (no máximo 3 meses) e os administradores indicados. Se corresponder, é aprovada como com um registo em tempo real; se não corresponder ou não for legível, segue para um revisor. Numa certidão selada, o selo do registo também é verificado.

PEP, poderes e alertas no claim

Campo em verified_claims.claimsSignificado
screening.pepno_match_found, possible_match (assinalado, não bloqueia), indication_only (apenas uma pesquisa pelo nome no Wikidata) ou not_screened.
authorityO que mostrou que o representante pode agir: register, extract, dazr_verification ou declared_by_representative.
flagsPresente quando há algo a analisar: pep_possible_match, high_risk_country.

Relatórios de verificação para auditorias

Para cada organização partilhada com a sua aplicação, pode obter um relatório de como e quando o Dazr a verificou, para o seu dossiê de auditoria. Existe enquanto a organização estiver verificada e enquanto a verificação estiver em curso, mostrando o que já foi feito.

Um relatório nunca contém imagens nem números de documentos de identificação, códigos de utilização única, o endereço PEC, endereços de e-mail nem qualquer morada que não seja a sede.

Relatórios de exemplo

Dois relatórios de exemplo com uma organização e pessoas fictícias, para que a sua equipa de conformidade veja o que recebe. Estão assinados com uma chave de exemplo, não com as chaves da Dazr: verifique-os com a chave pública de exemplo abaixo, nunca com o JWKS de produção.

Obter um relatório

Autentique-se com o seu ID de cliente e segredo de cliente, como no endpoint de token: HTTP Basic (client_secret_basic) ou o corpo do formulário de um POST (client_secret_post). Nunca coloque o segredo no URL. Use o id da organização das claims ou dos webhooks, ou simplesmente o verification.report_url que trazem.

curl -u "$DAZR_CLIENT_ID:$DAZR_CLIENT_SECRET" -o report.pdf \
  "https://identity.dazr.eu/oauth/verification-report?org=org_3k9x2m0q8w1v5t7a&format=pdf&lang=en"
ParâmetroSignificado
orgO id da organização.
formatpdf (predefinição) ou jws, os mesmos factos em JSON assinado.
langIdioma do PDF: en (predefinição), nl, it, de, fr, es ou pl.
docEm vez do relatório: declaration, a declaração assinada pelo administrador (só assinatura ou selo qualificado), ou extract, a certidão do registo comercial.

Só é possível obter organizações que pelo menos um dos seus utilizadores partilhou com a sua aplicação através de consentimento. Qualquer outra organização responde 404, tal como uma que não existe ou não tem verificação; um segredo de cliente errado responde 401. As aplicações sem segredo de cliente não podem obter relatórios. As transferências têm limite de frequência, e cada uma aparece na atividade da organização para os seus administradores, com o nome da sua aplicação. Na consola, a página da sua aplicação mostra as organizações ligadas com as mesmas transferências.

Verificar o JSON assinado

Com format=jws recebe um JWS compacto (ES256, cabeçalho typ dazr-verification-report+jwt), assinado com as mesmas chaves que os tokens de ID. As suas claims são iss, iat, jti (o ID do documento), sub (o id da organização), aud (o seu ID de cliente) e report, os factos. O PDF traz o mesmo JWS na última página e nos metadados (DazrVerificationReport), pelo que um PDF também pode ser verificado offline.

import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://identity.dazr.eu/oauth/jwks'));
// jws = the response body of format=jws, or the text from the PDF metadata
const { payload } = await jwtVerify(jws, jwks, {
  issuer: 'https://identity.dazr.eu',
  audience: process.env.DAZR_CLIENT_ID,
  typ: 'dazr-verification-report+jwt',
});
console.log(payload.report.verification.status, payload.report.verification.authority);

Deixar um auditor verificar a assinatura

Para uma assinatura ou selo qualificado, doc=declaration devolve a declaração assinada exatamente como foi carregada: um PDF assinado (PAdES) ou um ficheiro .p7m (CAdES). Um auditor pode validá-la de forma independente com o validador de demonstração DSS da Comissão Europeia: carregue o ficheiro, mantenha a política de validação predefinida e execute-a. O resultado mostra se a assinatura é qualificada (QESig, ou QESeal para um selo), quem assinou e o prestador de serviços de confiança da lista de confiança da UE. doc=extract devolve a certidão do registo comercial; uma certidão selada pelo registo pode ser validada da mesma forma.

O relatório é uma prova para o seu dossiê de auditoria. As entidades reguladas continuam responsáveis pela sua própria diligência devida quanto aos clientes.

O Dazr conserva a declaração assinada, a certidão e os dados do relatório enquanto a organização estiver verificada e durante 5 anos após o fim da verificação ou a eliminação da organização. Guarde as suas próprias cópias durante o tempo que as suas regras exigirem.

Chaves para relatórios antigos

Os relatórios são assinados com as mesmas chaves dos ID tokens, e essas chaves mudam. Cada chave que alguma vez assinou um relatório continua publicada em https://identity.dazr.eu/oauth/jwks/archive, com dazr_status current, previous ou retired, durante pelo menos 5 anos após a última utilização. Verifique um relatório antigo com o arquivo quando o seu kid já não estiver no JWKS.

Verificação de identidade (KYC)

Ative Permitir a verificação de identidade quando um início de sessão a pedir na consola e depois peça uma pessoa verificada com acr_values=urn:dazr:person:kyc. Ou assinale Exigir a verificação de identidade em cada início de sessão. Sem nenhuma destas definições, o valor acr é ignorado e nada é cobrado. Não é preciso nenhum scope adicional. Durante o início de sessão, a pessoa tira no telemóvel uma foto ao vivo do documento e uma selfie; um computador mostra um código QR. A Dazr lê o documento, compara os rostos e verifica o nome nas listas de sanções da UE, da ONU e da OFAC. Uma pessoa da Dazr analisa cada verificação, normalmente num dia útil.

Cada verificação custa 1,50 € sem IVA, do saldo de API da Dazr da sua organização. A pessoa nunca paga. Uma verificação é válida durante 12 meses. Quando outra aplicação a pede, a pessoa dá o consentimento num ecrã em vez de tirar novas fotos, e essa aplicação paga 1,50 €, uma vez por verificação. Se a sua aplicação voltar a pedi-la com prompt=consent, ou num início de sessão com uma verificação que ela já recebeu, é grátis.

O ID token e a user info contêm o claim kyc, e acr é urn:dazr:person:kyc:

"kyc": {
  "verified": true, "verified_at": 1791356184, "valid_until": 1822892184,
  "given_name": "ANNA", "family_name": "LINDQVIST", "birthdate": "1985-03-15",
  "nationality": "NO", "document_country": "NO",
  "sanctions": { "status": "no_match", "screened_at": 1791356184, "lists": ["eu", "un", "ofac"] }
}

sanctions.status é no_match, ou cleared_by_review quando um nome de uma lista era semelhante e um revisor concluiu que não é esta pessoa. Imagens e números de documentos nunca são partilhados. Após 12 meses o claim indica "verified": false: peça novamente.

As verificações são reais e cobradas também enquanto a sua aplicação está em testes.

Saldo

A sua organização pode pagar a verificação de empresa dos seus clientes. Na consola, abra a sua app e marque Pagamos a verificação de empresa dos nossos clientes. O preço é descontado do saldo da sua organização: um só saldo para todas as apps da organização e para as API Dazr pagas. Uma verificação custa 25 € sem IVA. Quando o saldo é insuficiente, o cliente paga como habitualmente e os seus administradores recebem um e-mail.

A sua aplicação só paga num início de sessão que pede a verificação de empresa, e uma vez por organização cliente. O que uma aplicação paga por dia por verificações de identidade e de empresa tem um limite: 250 € sem IVA, a não ser que o altere na consola em Limite diário de verificações. Quando é atingido, até ao dia seguinte as novas verificações de identidade são recusadas, os seus clientes pagam eles próprios a verificação de empresa e os seus administradores recebem um email.

Modo de teste

Enquanto a sua app não estiver publicada, uma verificação de empresa iniciada a partir de um início de sessão nela dá um resultado de teste. Não há pagamento, foto de documento nem revisor, e a verificação real da organização não muda. Os quatro últimos dígitos do número de registo ou de IVA da organização escolhem o resultado:

Quatro últimos dígitosResultadokyb.status
0001 ou qualquer outro númeroAprovadaapproved
0002Não aprovadarejected
0003Enviada a um revisorin_review
0004Correspondência com sançõesin_review
0005Expiradanone

Os resultados de teste têm test: true no claim, no webhook e no relatório, e só a sua app os vê enquanto não estiver publicada. Os números de registo são únicos na Dazr, por isso use o seu, por exemplo um número KVK neerlandês como 1234 0002. Na consola também pode enviar um webhook de teste para cada resultado.

Tokens e validades

TokenValidade e regras
Código de autorização60 segundos, utilização única, associado ao seu cliente, URI de redirecionamento e desafio PKCE. Usar um código duas vezes revoga os tokens que emitiu.
Token de acesso10 minutos. Um JWT assinado (ES256, typ at+jwt) com aud = o seu ID de cliente. Envie-o como Authorization: Bearer.
Token de ID10 minutos. ES256, com iss, sub, aud, exp, iat, auth_time, nonce e amr quando conhecido.
Refresh tokenSó com offline_access. Roda a cada utilização: guarde sempre o novo. Enviar novamente um refresh token antigo revoga todo o início de sessão. Expira após 30 dias sem utilização e, no máximo, após 180 dias.

As chaves de assinatura são rotativas. Escolha sempre a chave pelo kid do JWKS e atualize o JWKS quando vir um kid desconhecido.

Como a pessoa iniciou sessão

O amr do ID token (RFC 8176) indica como a pessoa iniciou sessão: ["otp"] para um código de utilização única por e-mail, ["hwk", "user"] para uma passkey com verificação do utilizador e ["fed"] para Google ou Microsoft.

Idioma

Envie ui_locales com o pedido de autorização, por exemplo ui_locales=de-AT de en. O primeiro idioma suportado pela Dazr é usado nos ecrãs de início de sessão e de consentimento. Os idiomas suportados estão em ui_locales_supported no documento de discovery.

O scope sign

O scope sign no documento de discovery é apenas para a Dazr Sign API. Permite que uma app envie documentos para assinar em nome da pessoa; ativa-o no portal Dazr Sign. O Sign in with Dazr Identity não precisa dele.

API do Dazr Files e WebDAV (só leitura)

A API do Dazr Files permite que a sua aplicação liste e transfira ficheiros do Dazr Files, por exemplo para fazer cópias de segurança. É só de leitura: nenhum pedido pode carregar, alterar, mover, partilhar ou eliminar nada. Ative-a para a sua aplicação na consola, na página da aplicação, em Dazr Files API. Usa a mesma aplicação, ID de cliente e segredo que Iniciar sessão com Dazr Identity, e os mesmos tokens de acesso.

Há duas formas de acesso. Um proprietário ou administrador de uma organização aprova a sua aplicação para os ficheiros partilhados da organização, e o seu servidor obtém tokens sem uma pessoa (o melhor para cópias de segurança automáticas). Ou uma pessoa autoriza a sua aplicação com o scope files.read, e a aplicação lê os ficheiros próprios dessa pessoa.

A referência completa, com cada endpoint, exemplos, erros, limites, o feed de alterações e a configuração WebDAV para rclone e Synology, está na documentação da API do Dazr Files.

Definições da organização que afetam o início de sessão

Erros

Desde que o seu ID de cliente e o URI de redirecionamento sejam válidos, os erros regressam ao seu URI de redirecionamento como error, error_description, state e iss: por exemplo invalid_request (como PKCE em falta ou simples), invalid_scope, unsupported_response_type, access_denied (a pessoa cancelou, ou a aplicação está em teste e a pessoa não é membro), login_required, consent_required e interaction_required (com prompt=none, quando falta uma organização verificada exigida). Com um cliente desconhecido ou um URI de redirecionamento não registado, o Dazr mostra uma página de erro e nunca redireciona. O endpoint de token responde com erros JSON como invalid_client, invalid_grant e unsupported_grant_type.

Terminar sessão

Para terminar a sessão de alguém, envie a pessoa para o endpoint de fim de sessão com id_token_hint (ou client_id), um post_logout_redirect_uri opcional registado nas definições da sua aplicação e state. O Dazr pergunta se também quer terminar a sessão do Dazr Identity nesse dispositivo e depois envia-a de volta. Revogue os refresh tokens de que já não precisa no endpoint de revogação.

Testar e entrar em produção

Uma aplicação nova está em teste: só os membros da sua organização podem iniciar sessão, e o ecrã de consentimento indica-o. Para entrar em produção, verifique a sua organização no Dazr Identity, adicione um URI de redirecionamento https:// e peça uma revisão para produção na consola. Alterar o nome, a finalidade, a política de privacidade ou os dados de uma aplicação em produção exige uma nova revisão.

Transferir uma aplicação para outra organização

Uma aplicação pode passar para outra organização registada na Dazr, por exemplo após uma venda ou uma reorganização. Um proprietário ou administrador inicia a transferência em Transferir aplicação, nas definições da aplicação, no Dazr Identity ou no portal do Sign. Um proprietário ou administrador da outra organização aceita-a ou recusa-a no prazo de 14 dias. Até lá, o remetente pode cancelar e nada muda.

O botão

Use o texto «Iniciar sessão com Dazr Identity» e o logótipo do Dazr como abaixo. Pode alterar o tamanho, mas não o logótipo, as cores nem o texto. Ligue-o à sua própria rota que inicia o fluxo.

<a href="/auth/dazr" style="display:inline-flex;align-items:center;gap:10px;height:44px;padding:0 18px;border-radius:22px;background:#18203a;color:#fff;font: 600 15px/1 'Dazr', system-ui, sans-serif;text-decoration:none">
  <svg width="20" height="20" viewBox="0 0 100 100" aria-hidden="true"><path d="M64.133 21.813 A6.634 6.634 0 0 1 66.455 31.054 A2.552 2.552 0 0 0 67.912 34.849 A36.74 36.74 0 0 1 93.010 60.100 A2.654 2.654 0 0 1 88.914 62.984 A44.91 44.91 0 0 0 62.003 54.621 A3.062 3.062 0 0 0 59.161 56.689 A73.49 73.49 0 0 0 56.170 92.578 A2.654 2.654 0 0 1 51.111 94.052 A36.74 36.74 0 0 1 52.093 63.128 A1.225 1.225 0 0 0 52.182 62.260 L48.938 50.153 A1.429 1.429 0 0 0 47.187 49.142 L35.080 52.387 A1.225 1.225 0 0 0 34.373 52.898 A36.74 36.74 0 0 1 8.083 69.210 A2.654 2.654 0 0 1 6.830 64.091 A73.49 73.49 0 0 0 36.416 43.557 A3.062 3.062 0 0 0 36.785 40.062 A44.91 44.91 0 0 0 16.087 20.937 A2.654 2.654 0 0 1 16.536 15.948 A36.74 36.74 0 0 1 50.954 25.058 A2.552 2.552 0 0 0 54.969 24.423 A6.634 6.634 0 0 1 64.133 21.813 Z" fill="#ffffff"/></svg>
  Sign in with Dazr Identity
</a>

Tipo de letra Dazr. O botão usa o tipo de letra Dazr, de utilização gratuita ao abrigo da SIL Open Font License. Onde o Dazr não estiver carregado, é usado o tipo de letra do sistema. Transfira o tipo de letra Dazr (ZIP com ficheiros TTF e WOFF2) para o alojar no seu próprio site:

/* woff2 files from the ZIP, copied to /fonts/ on your site */
@font-face { font-family: 'Dazr'; font-weight: 400; font-display: swap;
  src: url('/fonts/dazr-regular-latin.woff2') format('woff2'); }
@font-face { font-family: 'Dazr'; font-weight: 700; font-display: swap;
  src: url('/fonts/dazr-bold-latin.woff2') format('woff2'); }
.dazr-signin { font: 600 15px/1 'Dazr', system-ui, sans-serif; }

Um exemplo mínimo em Node.js

Node 18 ou posterior, sem dependências. Uma aplicação de servidor web com segredo de cliente; para um cliente público, retire o cabeçalho Authorization e envie client_id no corpo.

import crypto from 'node:crypto';
const issuer = 'https://identity.dazr.eu';
const clientId = process.env.DAZR_CLIENT_ID;
const clientSecret = process.env.DAZR_CLIENT_SECRET;
const redirectUri = 'https://app.example.eu/auth/dazr/callback';
const b64url = (buf) => Buffer.from(buf).toString('base64url');

// 1. Start: keep verifier, state and nonce in the user's session.
export function start(session) {
  session.verifier = b64url(crypto.randomBytes(32));
  session.state = b64url(crypto.randomBytes(16));
  session.nonce = b64url(crypto.randomBytes(16));
  const challenge = b64url(crypto.createHash('sha256').update(session.verifier).digest());
  return issuer + '/oauth/authorize?' + new URLSearchParams({
    response_type: 'code', client_id: clientId, redirect_uri: redirectUri,
    scope: 'openid profile email', state: session.state, nonce: session.nonce,
    code_challenge: challenge, code_challenge_method: 'S256',
  });
}

// 2. Callback: check state, exchange the code, verify the ID token.
export async function callback(session, query) {
  if (query.error) throw new Error('sign-in failed: ' + query.error);
  if (query.state !== session.state || query.iss !== issuer) throw new Error('state or issuer mismatch');
  const res = await fetch(issuer + '/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: 'Basic ' + Buffer.from(clientId + ':' + clientSecret).toString('base64'),
    },
    body: new URLSearchParams({ grant_type: 'authorization_code', code: query.code, redirect_uri: redirectUri, code_verifier: session.verifier }),
  });
  const tokens = await res.json();
  if (!res.ok) throw new Error(tokens.error);
  const claims = await verifyIdToken(tokens.id_token, session.nonce);
  return { sub: claims.sub, email: claims.email, name: claims.name, tokens };
}

async function verifyIdToken(idToken, nonce) {
  const [h, p, s] = idToken.split('.');
  const header = JSON.parse(Buffer.from(h, 'base64url'));
  const { keys } = await (await fetch(issuer + '/oauth/jwks')).json();
  const jwk = keys.find((k) => k.kid === header.kid);
  if (!jwk || header.alg !== 'ES256') throw new Error('unknown signing key');
  const ok = crypto.verify('sha256', Buffer.from(h + '.' + p),
    { key: crypto.createPublicKey({ key: jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' }, Buffer.from(s, 'base64url'));
  const c = JSON.parse(Buffer.from(p, 'base64url'));
  const now = Math.floor(Date.now() / 1000);
  if (!ok || c.iss !== issuer || c.aud !== clientId || c.exp < now - 30 || c.nonce !== nonce) throw new Error('invalid ID token');
  return c;
}

Limites

Os endpoints de autorização e de token têm limite de frequência. Se receber HTTP 429, aguarde e tente novamente; não repita num ciclo apertado.

EndpointLimite
/oauth/authorize120 pedidos por minuto por endereço IP
/oauth/token600 pedidos por minuto por endereço IP, e 300 por minuto por app
/oauth/userinfo1200 pedidos por minuto por endereço IP
/oauth/verification-report120 pedidos por minuto por endereço IP, e 60 por hora por app
Verificação empresarial6 inícios por hora por pessoa, e 10 por dia por organização
Webhooks de teste30 a cada 10 minutos por pessoa

As suas obrigações

A sua organização é responsável pelo tratamento, de forma independente, dos dados que recebe. Os Termos para Programadores do Dazr Identity definem o que pode fazer com eles, como os manter seguros e como comunicar violações. Dúvidas: hello@dazr.eu.

Para a sua análise de segurança e jurídica: o dossiê de segurança e compras.