Segurança e chaves de API

Tipos de chave

Permissão	O que pode fazer	Use para
full_access	Todos os endpoints	Suas próprias ferramentas, CLI, servidor MCP, scripts de administração
sending_access	Somente POST /emails e POST /emails/batch	Servidores de aplicação que apenas enviam e-mails

Chamar qualquer outro endpoint com uma chave sending_access retorna 401 restricted_api_key (“This API key is restricted to only send emails”).

Chaves restritas a um domínio

Uma chave sending_access também pode ser vinculada a um domínio com domain_id. Ela só poderá então enviar de endereços desse domínio; qualquer outro from retorna 401 restricted_api_key. Use isso para dar a cada produto ou cliente a sua própria chave.

Node.js

api-keys.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

// A key that can only send, and only from one domain.
const { data: key, error } = await spacepost.apiKeys.create({
  name: "worker-prod",
  permission: "sending_access",
  domainId: "0192e1c4-0000-7000-8000-000000000001",
});
if (error) throw new Error(error.message);
console.log(key.token); // sp_live_..., shown only once

const { data: keys } = await spacepost.apiKeys.list();
console.log(keys?.data.map((k) => `${k.name} ${k.prefix}... ${k.permission}`));

await spacepost.apiKeys.remove(key.id);

cURL

curl -X POST https://api.spacepost.dev/api-keys \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "worker-prod", "permission": "sending_access", "domain_id": "0192e1c4-0000-7000-8000-000000000001" }'

Response (the token is shown only once)

{ "id": "0192e1c4-0000-7000-8000-0000000000e1", "token": "sp_live_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" }

name tem de 1 a 50 caracteres. domain_id só é permitido com sending_access.

Como as chaves são armazenadas

• As chaves têm o formato sp_live_ seguido de 32 caracteres base62 aleatórios.
• O SpacePost armazena apenas um hash SHA-256. A chave completa é exibida uma vez, na criação. Se você a perder, crie uma nova chave.
• O painel e GET /api-keys mostram o prefixo (sp_live_ mais 4 caracteres), a permissão, o domínio e last_used_at.
• Excluir uma chave (DELETE /api-keys/{id}) a revoga imediatamente.

Bons hábitos

• Nunca coloque chaves em código do lado do cliente, apps móveis ou repositórios públicos. A API permite requisições cross-origin apenas para que playgrounds de API funcionem; envie e-mails a partir do seu servidor.
• Use uma chave por serviço e por ambiente, com nomes claros (worker-prod, ci-staging).
• Prefira sending_access, restrita a um domínio.
• Rotacione criando uma nova chave, fazendo o deploy dela, conferindo o last_used_at da antiga e só então excluindo a antiga.
• Guarde as chaves em um gerenciador de segredos ou em variáveis de ambiente, não no código.
• Revogue imediatamente se uma chave vazar. Se ela foi commitada no GitHub, considere-a comprometida.
• O SMTP usa a mesma chave como senha. Veja Relay SMTP.

Os segredos de webhook são separados

Cada webhook tem o seu próprio signing_secret. Veja Verificar assinaturas.

Transporte

Todo o tráfego usa TLS. A API é servida em https://api.spacepost.dev, e o relay SMTP em smtp.spacepost.dev:25976 exige STARTTLS antes da autenticação (TLS implícito na porta 465 ainda não é oferecido).

Outras proteções: as tentativas de autenticação SMTP com falha são limitadas por IP; os endpoints de webhook e as URLs de anexos devem resolver para endereços públicos (redes privadas são recusadas); os links de cancelamento de inscrição são assinados por contato.

Onde seus dados são armazenados

O SpacePost é operado pela Studio 404 d.o.o., uma empresa da UE na Eslovênia, e mantém os dados dos clientes na UE:

• Envio: Amazon SES na região eu-central-1 da AWS (Frankfurt, Alemanha). Todos os domínios enviam a partir dessa região.
• Aplicação e banco de dados: a API, o painel, os workers e o banco de dados Postgres rodam na Railway, na região da UE (Amsterdã, Países Baixos).
• Isolamento: cada equipe envia pelo seu próprio tenant do SES, então problemas de reputação de um cliente não afetam os outros.
• Site e documentação são páginas estáticas servidas pela rede global da Cloudflare; nenhum dado de cliente é armazenado lá.

Alguns provedores (AWS, Stripe, Railway) são empresas dos EUA. Eles estão listados, com o que processam e onde, na lista de suboperadores (disponível em inglês). Um adendo de processamento de dados conforme o GDPR faz parte dos Termos de Serviço, que são regidos pela legislação eslovena.

Relatar uma vulnerabilidade

Escreva para support@spacepost.dev com os detalhes. Por favor, não faça testes com dados de outros clientes.