Autenticação

Todas as requisições à API do NueForm exigem autenticação via chaves de API. Este guia mostra como gerar chaves, usá-las nas requisições e mantê-las seguras.

Gerando chaves de API

Para criar uma chave de API:

1. Faça login na sua conta NueForm.
2. Navegue até Profile e abra a aba Developer.
3. Clique em Create API Key.
4. Dê à sua chave um nome descritivo (por exemplo, "Backend de Produção" ou "Pipeline de CI").
5. Copie a chave imediatamente --- ela será exibida apenas uma vez.

Formato da chave de API

As chaves de API do NueForm seguem um formato consistente:

nf_<64 hex characters>

Toda chave começa com o prefixo nf_ seguido de 64 caracteres hexadecimais (32 bytes aleatórios). Por exemplo:

nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

No painel, as chaves são identificadas pelo prefixo (os primeiros 11 caracteres, por exemplo, nf_a1b2c3d4) para que você possa diferenciá-las sem expor o valor completo.

Usando sua chave de API

Inclua sua chave de API no cabeçalho Authorization de todas as requisições usando o esquema Bearer:

Authorization: Bearer nf_your_api_key_here

cURL

curl -X GET https://app.nueform.com/api/v1/forms \
  -H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;

const response = await fetch("https://app.nueform.com/api/v1/forms", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${NUEFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();
console.log(data);

Python (requests)

import os
import requests

api_key = os.environ["NUEFORM_API_KEY"]

response = requests.get(
    "https://app.nueform.com/api/v1/forms",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]
print(data)

Erros de autenticação

Se a autenticação falhar, a API retorna uma resposta 401 Unauthorized com uma mensagem descritiva:

Exemplo de resposta de erro:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

Gerenciamento de chaves

Limites

Cada conta NueForm pode ter até 10 chaves de API ativas ao mesmo tempo. Se você precisar criar uma nova chave e tiver atingido o limite, revogue uma chave existente primeiro.

Revogando chaves

Você pode revogar uma chave de API a qualquer momento na aba Developer do seu perfil. A revogação é imediata --- qualquer requisição usando uma chave revogada receberá uma resposta 401 Unauthorized.

Para revogar uma chave:

1. Vá em Profile > Developer.
2. Encontre a chave que deseja revogar (identificada pelo nome e prefixo).
3. Clique em Revoke.
4. Confirme a ação.

Rastreamento de último uso

O NueForm registra a última vez que cada chave de API foi usada. Confira a aba Developer para ver quais chaves estão em uso ativo e quais podem ser revogadas com segurança.

Requisitos de plano

O acesso à API é um recurso restrito que exige um plano pago:

Se você tentar usar uma chave de API em uma conta cujo plano não inclui acesso à API, receberá uma resposta 403 Forbidden:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

Boas práticas de segurança

Siga estas orientações para manter suas chaves de API seguras:

Nunca faça commit de chaves no controle de versão

Adicione seus arquivos de chave ao .gitignore e use variáveis de ambiente em vez disso. Se uma chave for acidentalmente commitada, revogue-a imediatamente e gere uma nova.

# .env (add .env to your .gitignore)
NUEFORM_API_KEY=nf_your_api_key_here

Use variáveis de ambiente

Armazene chaves de API em variáveis de ambiente em todos os ambientes --- desenvolvimento local, staging e produção. Nunca codifique chaves diretamente no código-fonte da sua aplicação.

// Good
const apiKey = process.env.NUEFORM_API_KEY;

// Bad --- never do this
const apiKey = "nf_a1b2c3d4...";

Use chaves separadas para cada ambiente

Crie chaves de API distintas para desenvolvimento, staging e produção. Isso limita o raio de impacto se uma chave for comprometida e facilita a revogação do acesso de um único ambiente.

Faça rotação de chaves regularmente

Crie novas chaves periodicamente e desative as antigas. O NueForm permite até 10 chaves ativas, então você pode criar uma nova chave, atualizar seus serviços, verificar que tudo funciona e depois revogar a chave antiga.

Restrinja o uso apenas ao lado do servidor

Chaves de API devem ser usadas apenas em código do lado do servidor. Nunca exponha sua chave de API em JavaScript do lado do cliente, aplicativos móveis ou qualquer código que rode no navegador de um usuário.