API atual/Referência completa/Autenticação avançada

Cadastrar passkey e confirmar por biometria

Cadastra uma passkey no aparelho do cliente logado e emite um token de curta duração para confirmar ações sensíveis.

Duas coisas acontecem aqui, ambas exigem um cliente já logado (Authorization: Bearer) e seguem o mesmo molde de duas chamadas, begin e finish.

Cadastrar a passkey liga o aparelho à conta, para os próximos logins sem senha (veja Login com passkey). Confirmar por biometria (step-up) prova, naquele momento, que a pessoa na frente da tela é o dono da conta. Hoje o token de step-up é exigido na aprovação de cotações de organizações corporativas que ativaram essa regra; sem ele a resposta é 403 step_up_required.

POST/api/v1/auth/webauthn/register/beginAutenticada

Iniciar o cadastro da passkey

Não recebe corpo. O options.publicKey vai para navigator.credentials.create.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/register/begin" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Opções de criação

json

{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "options": {
    "publicKey": {
      "rp": {
        "name": "Minha Loja",
        "id": "minhaloja.io.venddor.com.br"
      },
      "user": {
        "id": "M2YwYzJh...",
        "name": "maria.souza@example.com",
        "displayName": "Maria Souza"
      },
      "challenge": "Vb2n1c...",
      "pubKeyCredParams": [
        {
          "type": "public-key",
          "alg": -7
        }
      ],
      "timeout": 300000
    }
  }
}

Campos da resposta

ceremony_iduuid

Devolva no finish.

optionsobject

Opções WebAuthn de criação (rp, user, challenge, pubKeyCredParams, timeout).

POST/api/v1/auth/webauthn/register/finishAutenticada

Concluir o cadastro da passkey

Corpo da requisição

ceremony_iduuidobrigatório

O id recebido no begin.

credentialobjectobrigatório

Resultado de navigator.credentials.create serializado em JSON.

nicknamestring

Apelido para o cliente reconhecer o aparelho na lista (por exemplo, iPhone da Maria).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/register/finish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "nickname": "iPhone da Maria",
  "credential": {
    "id": "AQIDBAUG...",
    "rawId": "AQIDBAUG...",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBl...",
      "attestationObject": "o2NmbXRk..."
    }
  }
}'

Resposta

200Passkey cadastrada

json

{
  "credential": {
    "id": "9d3b5c10-2f7e-4a38-8d51-0c7e6b1a2f44",
    "nickname": "iPhone da Maria",
    "rp_id": "minhaloja.io.venddor.com.br",
    "last_used_at": null,
    "created_at": "2026-10-11T20:41:07Z"
  }
}

Campos da resposta

credential.iduuid

Id da passkey na plataforma. Use em DELETE /auth/webauthn/credentials/{id}.

credential.nicknamestring

Apelido informado.

credential.rp_idstring

Domínio ao qual a passkey está presa.

credential.last_used_atstring

Último uso (RFC 3339) ou null se nunca foi usada.

credential.created_atstring

Data de cadastro (RFC 3339, UTC).

POST/api/v1/auth/webauthn/stepup/beginAutenticada

Iniciar a confirmação por biometria

Sem corpo. Responde no mesmo formato do login/begin, mas restrito às passkeys do próprio usuário.

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/stepup/begin" \
  -H "Authorization: Bearer $TOKEN"

200Desafio criado

json

{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "options": {
    "publicKey": {
      "challenge": "qrTUyCAThPPHs-5tfQvPMVj_nlVvoKMx9mbcVZK11v4",
      "timeout": 300000,
      "rpId": "minhaloja.io.venddor.com.br"
    }
  }
}

POST/api/v1/auth/webauthn/stepup/finishAutenticada

Concluir a confirmação e obter o token de step-up

Corpo da requisição

ceremony_iduuidobrigatório

O id recebido em stepup/begin.

credentialobjectobrigatório

Resultado de navigator.credentials.get em JSON.

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/stepup/finish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "credential": {
    "id": "AQIDBAUG...",
    "rawId": "AQIDBAUG...",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBl...",
      "authenticatorData": "SZYN5Y...",
      "signature": "MEUCIQ...",
      "userHandle": "M2YwYzJh..."
    }
  }
}'

200Confirmado

json

{
  "step_up_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-10-11T20:52:00Z"
}

Campos da resposta

step_up_tokenstring

Token de curta duração, ligado ao usuário. Vai no cabeçalho X-Step-Up-Token.

expires_atstring

Expiração (5 minutos depois da confirmação, RFC 3339).

Erros

Status	Quando	Exemplo de corpo
400	`register/finish` com corpo inválido, prova inválida ou cerimônia expirada.	`{"error":"registration failed","detail":"..."}`
401	Sem token de acesso, ou token inválido.	`{"error":"authentication required"}`
401	`stepup/finish` com prova inválida ou cerimônia expirada.	`{"error":"step-up failed","detail":"..."}`
412	`stepup/begin` para um usuário sem nenhuma passkey.	`{"error":"no_passkey"}`
429	Limite de requisições da família `/auth/`.	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha ao gerar o desafio.	`{"error":"failed to begin registration","detail":"..."}`

Veja também

Cadastrar passkey e confirmar por biometria

Cadastra uma passkey no aparelho do cliente logado e emite um token de curta duração para confirmar ações sensíveis.

Duas coisas acontecem aqui, ambas exigem um cliente já logado (Authorization: Bearer) e seguem o mesmo molde de duas chamadas, begin e finish.

POST/api/v1/auth/webauthn/register/beginAutenticada

Iniciar o cadastro da passkey

Não recebe corpo. O options.publicKey vai para navigator.credentials.create.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/register/begin" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Opções de criação

json

{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "options": {
    "publicKey": {
      "rp": {
        "name": "Minha Loja",
        "id": "minhaloja.io.venddor.com.br"
      },
      "user": {
        "id": "M2YwYzJh...",
        "name": "maria.souza@example.com",
        "displayName": "Maria Souza"
      },
      "challenge": "Vb2n1c...",
      "pubKeyCredParams": [
        {
          "type": "public-key",
          "alg": -7
        }
      ],
      "timeout": 300000
    }
  }
}

Campos da resposta

ceremony_iduuid

Devolva no finish.

optionsobject

Opções WebAuthn de criação (rp, user, challenge, pubKeyCredParams, timeout).

POST/api/v1/auth/webauthn/register/finishAutenticada

Concluir o cadastro da passkey

Corpo da requisição

ceremony_iduuidobrigatório

O id recebido no begin.

credentialobjectobrigatório

Resultado de navigator.credentials.create serializado em JSON.

nicknamestring

Apelido para o cliente reconhecer o aparelho na lista (por exemplo, iPhone da Maria).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/register/finish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "nickname": "iPhone da Maria",
  "credential": {
    "id": "AQIDBAUG...",
    "rawId": "AQIDBAUG...",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBl...",
      "attestationObject": "o2NmbXRk..."
    }
  }
}'

Resposta

200Passkey cadastrada

json

{
  "credential": {
    "id": "9d3b5c10-2f7e-4a38-8d51-0c7e6b1a2f44",
    "nickname": "iPhone da Maria",
    "rp_id": "minhaloja.io.venddor.com.br",
    "last_used_at": null,
    "created_at": "2026-10-11T20:41:07Z"
  }
}

Campos da resposta

credential.iduuid

Id da passkey na plataforma. Use em DELETE /auth/webauthn/credentials/{id}.

credential.nicknamestring

Apelido informado.

credential.rp_idstring

Domínio ao qual a passkey está presa.

credential.last_used_atstring

Último uso (RFC 3339) ou null se nunca foi usada.

credential.created_atstring

Data de cadastro (RFC 3339, UTC).

POST/api/v1/auth/webauthn/stepup/beginAutenticada

Iniciar a confirmação por biometria

Sem corpo. Responde no mesmo formato do login/begin, mas restrito às passkeys do próprio usuário.

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/stepup/begin" \
  -H "Authorization: Bearer $TOKEN"

200Desafio criado

json

{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "options": {
    "publicKey": {
      "challenge": "qrTUyCAThPPHs-5tfQvPMVj_nlVvoKMx9mbcVZK11v4",
      "timeout": 300000,
      "rpId": "minhaloja.io.venddor.com.br"
    }
  }
}

POST/api/v1/auth/webauthn/stepup/finishAutenticada

Concluir a confirmação e obter o token de step-up

Corpo da requisição

ceremony_iduuidobrigatório

O id recebido em stepup/begin.

credentialobjectobrigatório

Resultado de navigator.credentials.get em JSON.

bash

curl -X POST "$BASE_URL/api/v1/auth/webauthn/stepup/finish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ceremony_id": "647bb41f-0aec-46ac-a2aa-9396f65ea311",
  "credential": {
    "id": "AQIDBAUG...",
    "rawId": "AQIDBAUG...",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBl...",
      "authenticatorData": "SZYN5Y...",
      "signature": "MEUCIQ...",
      "userHandle": "M2YwYzJh..."
    }
  }
}'

200Confirmado

json

{
  "step_up_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-10-11T20:52:00Z"
}

Campos da resposta

step_up_tokenstring

Token de curta duração, ligado ao usuário. Vai no cabeçalho X-Step-Up-Token.

expires_atstring

Expiração (5 minutos depois da confirmação, RFC 3339).

Erros

Status	Quando	Exemplo de corpo
400	`register/finish` com corpo inválido, prova inválida ou cerimônia expirada.	`{"error":"registration failed","detail":"..."}`
401	Sem token de acesso, ou token inválido.	`{"error":"authentication required"}`
401	`stepup/finish` com prova inválida ou cerimônia expirada.	`{"error":"step-up failed","detail":"..."}`
412	`stepup/begin` para um usuário sem nenhuma passkey.	`{"error":"no_passkey"}`
429	Limite de requisições da família `/auth/`.	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha ao gerar o desafio.	`{"error":"failed to begin registration","detail":"..."}`