Autenticação

Pré-requisitos

• Uma conta KivoSign com um plano que inclua acesso à API

Criar um token de API

Usando o token

Envie o token no cabeçalho Authorization das suas requisições HTTP.

cURL

curl https://app.kivosign.com.br/api/v2/envelope \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

JavaScript / TypeScript

const response = await fetch('https://app.kivosign.com.br/api/v2/envelope', {
  method: 'GET',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
  },
});

const envelopes = await response.json();

Usando o SDK TypeScript

O SDK cuida da autenticação. Informe a URL da KivoSign em serverURL:

import { Documenso } from '@documenso/sdk-typescript';

const client = new Documenso({
  apiKey: 'api_xxxxxxxxxxxxxxxx',
  serverURL: 'https://app.kivosign.com.br/api/v2',
});

const documents = await client.documents.find();

Também há SDKs para TypeScript, Python e Go.

URL base da API

Segurança do token

O token de API dá acesso total à API da equipe para a qual foi criado. Siga estas práticas para mantê-lo seguro:

• Nunca faça commit de tokens no controle de versão. Use variáveis de ambiente.
• Use nomes descritivos. Nomes como zapier-prod ou backend-homologacao ajudam a identificar o uso de cada token.
• Defina uma validade. Prazos mais curtos reduzem o risco se um token vazar.
• Troque os tokens com frequência. Crie tokens novos e revogue os antigos periodicamente.
• Use um token por integração. Se um vazar, basta revogar aquele token.
• Revogue tokens sem uso. Exclua na página de Tokens de API os tokens de que não precisa mais.

Variáveis de ambiente

Guarde o token em uma variável de ambiente em vez de deixá-lo fixo no código:

# .env (não faça commit deste arquivo)
KIVOSIGN_API_KEY=api_xxxxxxxxxxxxxxxx

const client = new Documenso({
  apiKey: process.env.KIVOSIGN_API_KEY,
  serverURL: 'https://app.kivosign.com.br/api/v2',
});

Escopo do token

O token de API tem acesso total à API da equipe para a qual foi criado, incluindo:

• Criar, consultar, atualizar e excluir documentos
• Gerenciar destinatários e campos
• Acessar modelos

Ainda não é possível criar tokens com escopo ou permissões limitadas.

Revogar um token

Para revogar um token:

O token revogado para de funcionar na hora. Integrações que usam esse token passam a receber erro 401 Unauthorized.

Solução de problemas

Próximos passos

• Faça sua primeira chamada à API - Crie um documento pela API
• Referência da API - Conheça os endpoints disponíveis