Integre cálculos estruturais com credenciais de menor privilégio.

01 · Início rápido

Da criação à primeira chamada

1. 1

   Crie

   Entre na conta, escolha um nome e conceda somente os escopos necessários.

2. 2

   Copie uma vez

   A chave completa aparece só na criação. Salve-a imediatamente em um cofre.

3. 3

   Envie como Bearer

   Use o header Authorization em HTTPS; nunca coloque a chave na URL.

export STRUCTURALTECH_API_KEY="cole-a-chave-no-seu-cofre"

curl --request POST \
  --url "https://structuraltech.com.br/v1/geometry/rectangular-section" \
  --header "Authorization: Bearer $STRUCTURALTECH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"b":14,"h":40}'

O exemplo usa uma variável de ambiente fictícia e nunca contém uma chave real. O endpoint de geometria exige compute:write, consome um crédito e aceita Idempotency-Key para deduplicar retries.

02 · Autenticação

Um único header, sem alias

Envie Authorization: Bearer <chave>. O header x-api-key não é aceito. Chaves de teste começam com stk_test_; chaves de produção, com stk_live_. Uma chave usada no ambiente errado falha com 401.

const response = await fetch(
  'https://structuraltech.com.br/v1/geometry/rectangular-section',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.STRUCTURALTECH_API_KEY}`,
      'Content-Type': 'application/json',
      // Uma chave por pedido. Para calcular com outros parâmetros, gere outra.
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({ b: 14, h: 40 }),
  },
);

if (!response.ok) throw new Error(`API respondeu ${response.status}`);
const result = await response.json();

03 · Escopos

Conceda somente o necessário

04 · Ciclo de vida

Expiração, revogação e rotação sem downtime

05 · Erros e limites

Trate status HTTP e faça backoff

Cada chave tem dois baldes independentes. Rotas de cálculo — beam2d, frame2d, frame3d, grelhas, pilares, materiais e memorial — permitem 45 requisições por minuto e 10 a cada 10 segundos. As demais rotas, como projetos e consultas normativas, permitem 120 por minuto e 20 a cada 10 segundos. Estourar um balde não bloqueia o outro.

O contador acompanha a chave, não o IP nem a conexão: disparar chamadas em paralelo não multiplica a cota, apenas concentra os hits na mesma janela. Acompanhe os headers X-RateLimit-Remaining de cada resposta e faça backoff a partir do Retry-After. O limite ainda não deve ser tratado como SLA contratual durante o pré-lançamento.

06 · Segurança

Práticas obrigatórias no cliente

• Armazene a chave em um secret manager ou variável protegida.
• Nunca versione, registre em logs ou envie a chave em query string.
• Use HTTPS e defina timeouts nas chamadas.
• Gere uma Idempotency-Key por pedido; mantenha-a só entre tentativas do mesmo pedido.
• Revogue imediatamente uma chave suspeita de exposição.
• Monitore último uso e remova credenciais abandonadas.