Configurar a API REST

Todo produto NimbusNexus é uma API REST: JSON sobre HTTPS, com sua chave de API no header Authorization. Esta página leva você de nenhuma chave até a primeira chamada bem-sucedida. Escolha uma linguagem no topo da página e os exemplos a acompanham. REST significa curl; TypeScript, Python e Go usam o cliente HTTP habitual de cada linguagem, sem precisar de SDK.

1 · Obter uma chave de API

Apps: Webhooks, Inboxes, Códigos QR e Request Bins. Abra API keys no console da sua conta e crie uma chave para o produto que você quer chamar. Cada chave pertence a um produto. Escolha o escopo dela ali: admin, read ou, para Webhooks, também publish. Copie a chave quando ela aparecer, porque ela é mostrada só uma vez. Uma chave de app é um JWT, então começa com eyJ.

Infraestrutura: VMs, armazenamento, bancos de dados e rede. Crie a chave no painel, em Settings → API keys. Ela tem escopo de um projeto. Autenticação cobre escopos e rotação.

Mantenha a chave fora do seu código-fonte. Exporte-a no seu shell ou guarde-a no seu cofre de segredos:

Shell

export WEBHOOKS_API_KEY="<your-api-key>"

2 · Enviar a chave em toda requisição

Envie a chave como um token Bearer. As APIs dos apps também a aceitam como X-API-Key: <key>.

HTTP

Authorization: Bearer <your-api-key>

Cada produto tem a própria URL base:

Produto	URL base
Webhooks	`https://webhooks.nimbusnexus.net/v1`
Inboxes	`https://inboxes.nimbusnexus.net/v1`
Códigos QR	`https://qr.nimbusnexus.net/v1`
Request Bins	`https://bins.nimbusnexus.net/v1`
Infraestrutura	`https://api.nimbusnexus.net`

3 · Fazer a primeira chamada

GET /v1/auth/me no Webhooks retorna a chave que você enviou: o escopo dela e o workspace ao qual ela pertence. Ele não lê mais nada, então qualquer chave válida pode chamá-lo.

curl https://webhooks.nimbusnexus.net/v1/auth/me \
  -H "Authorization: Bearer $WEBHOOKS_API_KEY"

A resposta indica o seu workspace:

JSON

{
  "scope": "admin",
  "workspace_id": "<workspace-id>"
}

Os outros campos dizem que tipo de credencial é esta. Para uma chave de API, email e created_at são null.

4 · Ler os erros

Uma requisição que falha responde com um status 4xx ou 5xx e um único formato de erro em todos os produtos:

JSON

{
  "error": {
    "code": "unauthorized",
    "message": "…",
    "details": { "reason": "missing" },
    "request_id": "…"
  }
}

Tome decisões com base em code, não no status nem na mensagem. unauthorized significa que nenhuma chave chegou ou que a chave foi revogada. invalid_credential significa que a chave não é válida: gere uma nova, porque tentar de novo não vai ajudar. forbidden significa que a chave é válida, mas não pode fazer isso: falta o escopo ou a função, ou o produto não está ativado para o seu workspace. Autenticação e Erros listam todos os códigos. Informe o request_id quando falar com o suporte.

Próximos passos

Referência da API: todas as operações de todos os produtos, com a chamada na sua linguagem.
SDKs e a CLI: as mesmas chamadas, com retentativas, verificação de assinatura e paginação resolvidas para você.
Inícios rápidos dos produtos: Webhooks, Inboxes, Request Bins, sua primeira VM.