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.
X-Api-Key: <sua-chave> em cada requisição da API pública.
A chave dá acesso aos dados da conta a que pertence.
A chave não expira sozinha — rotacione você mesmo.
Gerando sua chave
- Acesse o painel da ForSign e faça login.
- Vá em Configurações > Desenvolvedor.
- 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
| Status | Significado |
|---|---|
401 Unauthorized | X-Api-Key ausente ou inválida. |
403 Forbidden | Chave 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.