Docs
Começar

Autenticação

Como gerar sua X-Api-Key, enviá-la em cada requisição e tratar erros.

A autenticação é feita por X-Api-Key — uma chave secreta que você gera no painel e envia no header de cada requisição à API pública.

Header em toda chamada

X-Api-Key: <sua-chave> em cada requisição da API pública.

Escopo da sua conta

A chave dá acesso aos dados da conta a que pertence.

Sem expiração automática

A chave não expira sozinha — rotacione você mesmo.

Gerando sua chave

  1. Acesse o painel da ForSign e faça login.
  2. Vá em Configurações > Desenvolvedor.
  3. Na aba Configurações, copie sua API-Key.

Nunca exponha a chave em código-fonte público. Use variáveis de ambiente ou um secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault). Uma chave vazada dá acesso completo aos dados da sua conta.

Enviando em cada requisição

Adicione o header X-Api-Key em todas as chamadas autenticadas:

curl -H "X-Api-Key: $FORSIGN_API_KEY" https://api.forsign.digital/api/v2/...

Exemplos por linguagem

curl -X POST "https://api.forsign.digital/api/v1/operation" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $FORSIGN_API_KEY" \
  -d '{"name":"Contrato","files":[]}'
const axios = require('axios');

const apiKey = process.env.FORSIGN_API_KEY;
const client = axios.create({
  baseURL: 'https://api.forsign.digital',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey,
  },
});

try {
  const { data } = await client.post('/api/v1/operation', { /* payload */ });
  console.log(data);
} catch (err) {
  if (err.response?.status === 401) {
    console.error('Chave inválida, ausente ou em formato incorreto.');
  }
  throw err;
}
using System.Net.Http;
using System.Net.Http.Headers;

var apiKey = Environment.GetEnvironmentVariable("FORSIGN_API_KEY");

var client = new HttpClient
{
    BaseAddress = new Uri("https://api.forsign.digital"),
};
client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.PostAsJsonAsync("/api/v1/operation", new { /* payload */ });
if ((int)response.StatusCode == 401)
{
    throw new InvalidOperationException("X-Api-Key ausente ou inválida.");
}
response.EnsureSuccessStatusCode();
import os, requests

api_key = os.environ["FORSIGN_API_KEY"]
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": api_key,
}

response = requests.post(
    "https://api.forsign.digital/api/v1/operation",
    headers=headers,
    json={"name": "Contrato", "files": []},
)
if response.status_code == 401:
    raise RuntimeError("Chave inválida/ausente.")
response.raise_for_status()
print(response.json())
<?php
$apiKey = getenv('FORSIGN_API_KEY');
$payload = ['name' => 'Contrato', 'files' => []];

$ch = curl_init('https://api.forsign.digital/api/v1/operation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 401) {
    throw new RuntimeException('Chave inválida ou ausente.');
}
echo $response;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var apiKey = System.getenv("FORSIGN_API_KEY");
var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.forsign.digital/api/v1/operation"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", apiKey)
    .POST(HttpRequest.BodyPublishers.ofString("{\"name\":\"Contrato\",\"files\":[]}"))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 401) {
    throw new RuntimeException("Chave inválida ou ausente.");
}
System.out.println(response.body());
package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("FORSIGN_API_KEY")
    body := bytes.NewBufferString(`{"name":"Contrato","files":[]}`)

    req, _ := http.NewRequest("POST", "https://api.forsign.digital/api/v1/operation", body)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode == 401 {
        panic("X-Api-Key inválida ou ausente")
    }

    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Erros possíveis

StatusSignificado
401 UnauthorizedX-Api-Key ausente ou inválida.
403 ForbiddenChave válida, mas sem permissão para esse recurso.

O corpo das respostas 401 é vazio, por segurança. Se está recebendo 401, confira se o header X-Api-Key está presente e se a chave é a correta para o ambiente.

Rotação e revogação

A ForSign não rotaciona chaves automaticamente. Boas práticas:

  • Rotacione a cada 90 dias em produção.
  • Se uma chave vazou: Gere uma nova imediatamente e atualize seus clientes.

Uma chave = uma conta. Todos os endpoints autenticados por ela operam sobre os dados da sua conta. Não reutilize a mesma chave em ambientes diferentes.

Próximo passo

Veja o fluxo completo de uma operação →

On this page