Como Obter Credenciais (API Key / OAuth2) da API de Assinatura

Antes de enviar o primeiro documento para assinatura via API, você precisa de uma coisa: credenciais válidas. Na API SignDocs, isso significa criar um aplicativo, obter o seu client_id e client_secret e trocá-los por um access token OAuth2. Este guia mostra, passo a passo, como gerar essas credenciais, gerenciar scopes, separar homologação de produção e proteger seus segredos seguindo as boas práticas de segurança.

Diferente de muitas APIs que distribuem uma "API key" estática, a API SignDocs adota o fluxo OAuth2 client-credentials: você nunca envia o segredo nas chamadas de negócio, apenas um token de curta duração. É um modelo mais seguro, mais auditável e alinhado às exigências de clientes regulados.

Se você ainda está avaliando a plataforma, vale começar pela visão geral da API de assinatura digital e por o que é uma API de assinatura digital. Já se o objetivo é colocar a integração de pé rapidamente, o roteiro de primeiros passos em 5 minutos complementa este artigo. Aqui, o foco é exclusivamente o ponto de partida de toda integração: as credenciais.

API key estática vs. OAuth2 client-credentials

Muitos desenvolvedores chegam procurando por "como obter a API key" da assinatura digital. É um termo genérico e perfeitamente compreensível, mas é importante entender o que está por trás dele na prática moderna de segurança de APIs.

Uma API key tradicional é uma string longa que você anexa a cada requisição (em um header ou query string). É simples de usar, porém carrega problemas estruturais: não expira sozinha, é difícil de rotacionar sem downtime, costuma carregar permissões amplas demais e, se vaza, dá acesso total até ser revogada manualmente.

O OAuth2 client-credentials resolve isso separando identidade de autorização. Você recebe duas peças de informação:

• client_id — identificador público do seu aplicativo. Não é segredo; pode aparecer em logs.
• client_secret — o segredo de fato. Combinado com o client_id, é trocado por um token. Nunca trafega nas chamadas de negócio.

O segredo é usado uma única vez por ciclo, contra o endpoint de token, para obter um access token de vida curta. Esse token (um JWT) é o que viaja nas chamadas reais da API. Os benefícios são diretos:

Passo a passo: criando seu aplicativo e gerando credenciais

O processo de obtenção das credenciais de homologação (HML) é self-service e leva poucos minutos no painel da SignDocs. Dois pré-requisitos importantes: a conta precisa ser Pessoa Jurídica (com CNPJ), e o fluxo deve ser feito pela web ou pelo app Android — no iOS a opção Enterprise não aparece, por restrição da App Store.

1. Crie sua conta PJ

Faça o cadastro gratuito em app.signdocs.com.br, marcando Pessoa Jurídica e preenchendo o CNPJ.

2. Abra o wizard de plano

No dashboard, abra o menu de Perfil (avatar) → Gerenciar Plano. Responda ao questionário até chegar ao card "Plano Enterprise — Orçamento personalizado" e, no campo de necessidades, descreva seu caso de uso de integração (por exemplo: "Integração da External API no nosso backend; quero credenciais HML para testar OAuth2 + transações"). Clique em Receber Orçamento — sua conta é marcada como Enterprise imediatamente, sem espera nem revisão manual.

3. Abra o API Dashboard

De volta ao Perfil, aparece o botão Abrir API Dashboard (visível apenas para contas Enterprise). Clique nele.

4. Ative as credenciais HML

Na tela "Ativar credenciais HML", preencha o nome da empresa (e, opcionalmente, o CNPJ), aceite os termos de uso do sandbox e clique em Ativar credenciais HML.

5. Copie tudo — o modal aparece uma única vez

Um modal exibe o tenantId, o client_id, o client_secret e as URLs do sandbox e da documentação. Atenção: o client_secret é mostrado apenas uma vez. Copie e armazene imediatamente em um cofre de segredos. Se perdê-lo, é preciso reprovisionar: o client_id continua o mesmo, mas um novo segredo é gerado e o antigo é invalidado.

Trocando as credenciais por um access token

Com o client_id e o client_secret em mãos, o próximo passo é obter um access token. Você faz uma requisição POST ao endpoint de token, enviando as credenciais e o grant_type=client_credentials. A resposta traz o token que você usará nas demais chamadas.

Requisição de token (cURL)

Uma resposta de sucesso retorna o access token, o tipo (Bearer), o tempo de expiração em segundos e os scopes efetivamente concedidos:

Usando o token nas chamadas de negócio

De posse do access_token, você o envia no header Authorization de cada requisição. Por exemplo, ao criar uma sessão de assinatura expressa:

Cacheando e renovando o token (Node.js)

Como o token expira em 15 minutos (900 segundos, conforme expires_in), o cliente deve reutilizá-lo entre chamadas e renová-lo um pouco antes de expirar, em vez de solicitar um novo a cada requisição:

Note que o client_id e o client_secret vêm de process.env — nunca hardcoded. Esse é um ponto não negociável de segurança que aprofundamos mais abaixo.

Scopes: aplicando o menor privilégio

Scopes são as permissões granulares concedidas a cada credencial. Em vez de uma chave "tudo ou nada", você restringe cada app exatamente ao que ele precisa. Se um segredo vazar, o impacto fica limitado aos scopes daquele app.

JWT ES256 e chaves em KMS

O access token que você recebe é um JWT (JSON Web Token) assinado pela plataforma com ECDSA na curva P-256 (ES256). As chaves privadas de assinatura ficam protegidas em KMS (Key Management Service), nunca expostas. Isso garante que um token Bearer não pode ser forjado: sua autenticidade é verificável criptograficamente pela chave pública correspondente.

Na prática, você não manipula essa chave — basta enviar o token Bearer e a SignDocs cuida da emissão e validação. O conhecimento de ES256 é útil para entender as garantias do sistema: com uma chave de apenas 256 bits, o ECDSA oferece segurança equivalente a uma RSA de 3072 bits, com tokens menores e verificação mais rápida. Para clientes regulados que precisam de uma camada adicional de autenticação de canal, a resposta é o mTLS — assunto da próxima seção e detalhado no guia de segurança mTLS enterprise da API.

mTLS para clientes enterprise e regulados

Para integrações de alta exigência — instituições financeiras, contextos BACEN/Open Finance e setores regulados — a SignDocs oferece mTLS (mutual TLS) em adição ao OAuth2. No TLS comum, apenas o servidor apresenta certificado; no mTLS, cliente e servidor se autenticam mutuamente por certificados.

Na prática, isso significa que, além de possuir credenciais OAuth2 válidas, o seu cliente precisa apresentar um certificado cliente reconhecido para sequer estabelecer a conexão. É uma camada adicional que torna o vazamento de um segredo insuficiente para acessar a API a partir de uma máquina não autorizada. Os passos de provisionamento de certificados, CA confiável e configuração estão no guia dedicado de mTLS enterprise.

Separando credenciais de homologação e produção

Um erro comum e perigoso é misturar credenciais de ambientes. Homologação e produção devem usar apps, credenciais e hosts totalmente separados.

Na sua aplicação, mantenha as credenciais de cada ambiente em cofres separados e selecione a configuração por variável de ambiente (por exemplo, STAGE=hml vs STAGE=prod). Nunca aponte código de produção para credenciais de teste, nem vice-versa.

Rotação de credenciais

Segredos devem ser rotacionados periodicamente — a Política de Uso Aceitável da API prevê rotação a cada 12 meses — e imediatamente após qualquer suspeita de vazamento (segredo em log, em commit, em ticket de suporte). Na SignDocs, a rotação é feita reprovisionando a credencial: o client_id permanece o mesmo, um novo client_secret é gerado e o segredo antigo é invalidado no ato. Como não há período de sobreposição, planeje a troca:

1. Prepare sua aplicação para ler o segredo de um cofre em runtime, sem exigir novo deploy.
2. Reprovisione a credencial e copie o novo client_secret do modal (exibido uma única vez).
3. Atualize o cofre de segredos com o novo valor imediatamente.
4. Force a renovação do token em cache — tokens já emitidos continuam válidos até expirarem (15 minutos), o que dá uma pequena margem natural.
5. Valide que as chamadas de negócio voltaram a autenticar normalmente.

Boas práticas de segurança para credenciais

Reunindo tudo, este é o checklist de segurança que toda integração com a API SignDocs deve seguir:

• Nunca faça commit de segredos. Adicione .env ao .gitignore e use ferramentas como git-secrets ou scanners de segredo no CI.
• Nada de segredo no frontend. O fluxo client-credentials é server-to-server. Apps web, mobile e SPAs jamais devem conter o client_secret.
• Cofre de segredos em produção. Prefira AWS Secrets Manager, Google Secret Manager ou Vault a variáveis de ambiente em texto plano.
• Menor privilégio nos scopes. Conceda apenas o necessário; crie apps separados por função.
• Rotacione periodicamente. E imediatamente após qualquer suspeita de exposição.
• Separe HML de PROD. Credenciais, hosts e cofres distintos por ambiente.
• Valide webhooks. Use a verificação de assinatura HMAC-SHA256 descrita em webhooks e eventos da API de assinatura para confiar nos eventos recebidos.
• Considere mTLS em contextos regulados, somando autenticação de certificado ao OAuth2.
• Monitore o uso. Acompanhe a emissão de tokens e chamadas por app para detectar anomalias cedo.

Com as credenciais geradas e protegidas, o próximo passo natural é colocar a integração em prática — siga o roteiro de primeiros passos em 5 minutos para o seu primeiro envio e valide tudo no ambiente de homologação (sandbox) antes de ir para produção.