Chaves escopadas

Uma chave escopada só faz o que foi marcado ao gerá-la: um conjunto de operações (permissões) e um conjunto de projetos. Use uma chave por integração, com o mínimo de que ela precisa. A chave legada continua existindo e acessa todas as rotas da API em todos os projetos da empresa.

Gerar a chave

No painel da Dynadok, em Chaves de API, um administrador da empresa gera a chave com a opção Escopada (recomendado) e escolhe:

• Operações: as permissões listadas na tabela abaixo. Algumas incluem outras: quem pode enviar documentos também pode ver documentos e participantes, por exemplo.
• Projetos: Projetos selecionados (só os escolhidos) ou Todos os projetos, que inclui também os projetos criados depois.

O uso é idêntico ao da chave legada: header x-api-key, mesmo formato <uuid>.<segredo>, mesmas rotas e mesmas respostas. O acesso pode ser alterado depois no painel sem trocar o segredo, e uma chave legada pode ser restringida da mesma forma.

Permissão exigida por rota

Todas as rotas abaixo ficam sob /v1/api.

rota	permissão (scope)	nome no painel
GET /catalog/documents, GET /catalog/declarations, GET /catalog/custom-document-types	perm:document-catalog:read	Consultar catálogo de documentos
GET /projects/{projectId}/competencies	perm:project-competency:read	Ver competências
POST /projects/{projectId}/competencies	perm:project-competency:create	Criar competências
POST /competencies/{competencyId}/participants/search	perm:participant:read	Ver participantes
POST /competencies/participants/search	perm:participant:read	Ver participantes
POST /participants/search	perm:participant:read	Ver participantes
GET /participants/{participantId}	perm:participant:read	Ver participantes
GET /participants/{participantId}/custom-fields	perm:participant:read	Ver participantes
GET /competencies/{competencyId}/participants/{participantId}/submission/status	perm:participant:read	Ver participantes
POST /competencies/{competencyId}/participant	perm:participant:create	Cadastrar participantes e dependentes
POST /participants/{participantId}/dependents	perm:participant:create (atualizar um dependente que já existe exige também perm:participant:update)	Cadastrar participantes e dependentes
DELETE /competencies/{competencyId}/participants/{participantId}/dependents/{dependentId}	perm:participant:update	Editar participantes e dependentes
DELETE /competencies/{competencyId}/participants/{participantId}	perm:participant:delete	Excluir participantes
POST /competencies/{competencyId}/participants/{participantId}/submission/conclude	perm:participant:submission:conclude	Concluir envio em nome do participante
PATCH /competencies/{competencyId}/participants/{competencyParticipantId}/status	perm:participant:status:update	Alterar status do participante
POST /competencies/{competencyId}/participants/{participantId}/authenticated-link	perm:participant:authenticated-link:create	Emitir link autenticado de participante
GET /participants/{participantId}/document-requests	perm:participant-document:read	Ver documentos
GET /participants/{participantId}/documents	perm:participant-document:read	Ver documentos
GET /participants/{participantId}/documents-data	perm:participant-document:read	Ver documentos
GET /participant-documents/{participantDocumentId}	perm:participant-document:read	Ver documentos
POST /competencies/{competencyId}/participants/{participantId}/documents	perm:participant-document:upload	Enviar documentos pelo participante
POST /competencies/{competencyId}/participants/{participantId}/input-documents	perm:participant-document:upload	Enviar documentos pelo participante
POST /competencies/{competencyId}/participants/{participantId}/documents/justification	perm:participant-document:upload	Enviar documentos pelo participante
POST /competencies/{competencyId}/participants/{participantId}/participant-documents/{participantDocumentId}/request-review	perm:participant-document:review:request	Pedir revisão em nome do participante
GET /participant-documents/{participantDocumentId}/file-url	perm:participant-document:download	Baixar documentos do participante
PATCH /participant-documents/{participantDocumentId}/status	perm:participant-document:status:update	Avaliar documentos

Sem a permissão da rota, ou com o recurso fora dos projetos da chave, a resposta é 403, no envelope de erro:

{
  "success": false,
  "status": 403,
  "message": "Scoped credential is not allowed on this resource",
  "errors": [],
  "context": null,
  "extraData": {}
}

A message varia (recurso fora dos projetos da chave vem com "Access denied"); trate pelo status.

Rotas que só aceitam chave legada

Toda rota da API que não está na tabela acima responde 403 a uma chave escopada, mesmo que ela tenha todas as permissões. Hoje são:

• PATCH /participants/{participantId} e PATCH /participants/{participantId}/custom-fields
• POST /competencies/{competencyId}/send-invite
• POST /documents e GET /documents/{_id}
• PATCH /documents/{participantDocumentId}/computed-fields e PATCH /participant-documents/{participantDocumentId}/computed-fields
• POST .../document-group/{documentGroupId}/split-and-redistribute e GET /competencies/execute-validation-code-for-split/{splitId}
• todas as rotas de /datasets e de /credit-transfer-analyses

Para essas operações, use uma chave legada.

O que muda com a chave escopada

As rotas aceitas se comportam como na chave legada, com estas diferenças:

• Campos que dependem de permissão saem da resposta. Sem perm:participant-document:download, links e caminhos de arquivo (documentUrl, fileUrl, files e afins) não vêm. Sem permissão de histórico, validationCheckpoints e os históricos do documento e do participante também não vêm. O campo é omitido, não volta vazio: a ausência não significa que o documento não tenha arquivo ou histórico. Campos de fórmula de validação e de estatísticas nunca vêm para chave escopada.
• Envio de documento sem rules. No envio (.../documents), mandar rules responde 403: a chave pode enviar, não trocar as regras de validação do slot. O dependentId, quando enviado, precisa ser de um dependente do participante da rota, e extraData não pode trazer as chaves competencyParticipantId, projectCompetencyId, projectId nem companyId.
• Busca por CPF só nos projetos da chave. POST /participants/search devolve apenas participações dos projetos que a chave alcança; com a chave limitada a projetos e nenhum projeto liberado, a resposta é uma lista vazia.
• Criar competência sem cópia. Em POST /projects/{projectId}/competencies, competencyIdToCopy ou qualquer isToCopy* responde 403.
• POST /competencies/participants/search filtra só por telefone. Com chave escopada, a rota considera apenas os 20 projetos publicados mais recentes que a chave alcança, filtra pelo phone quando ele vem com 11 dígitos (com ou sem máscara) e devolve até 50 participantes, os mais recentes, em página única. Cada item traz _id, name, status, createdAt, project._id e competency (_id, publicTitle, createdAt). Os demais filtros do corpo são ignorados.

Token temporário

Opcional. Em vez de mandar a chave em toda chamada, a integração pode trocá-la por um token de 10 minutos e usar o token no header Authorization. Só chave escopada pode ser trocada.

curl --request POST 'https://api.dynadok.com/v1/mcpAuthorization/api-token' \
  --header 'x-api-key: 550e8400-e29b-41d4-a716-446655440000.SUA_CHAVE'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "perm:participant:read perm:participant-document:read"
}

Essa resposta não usa o envelope { code, message, timestamp, data }: os campos vêm na raiz. scope traz as permissões que o token carrega.

curl 'https://api.dynadok.com/v1/api/participants/6500a1b2c3d4e5f600000002' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...'

• Mande só x-api-key na troca. Com Authorization junto, ou com chave legada, inválida ou revogada, a resposta é 401 com { "error": "invalid_client" }.
• O token vale para as rotas de /v1/api com as mesmas permissões e projetos da chave. Mudanças de acesso no painel e a revogação da chave valem também para tokens já emitidos.
• Token vencido ou inválido responde 401. Peça outro: não há renovação.
• A troca aceita até 60 pedidos por minuto por IP; acima disso responde 429 com o header Retry-After.