Autenticação

A API de Integrações suporta dois métodos de autenticação:

Método	Uso	Token
API Keys	Integrações machine-to-machine	`sk_<id>_<secret>`
OAuth2 Authorization Code	Automações (Zapier, Make, n8n)	Bearer JWT / `bit_*`

API Keys

Formato do token

sk_<publicId>_<secret>

O token é exibido apenas uma vez no momento da criação. Armazene-o de forma segura imediatamente.

Como usar

Envie o token no header Authorization:

# Com prefixo Bearer
curl -H "Authorization: Bearer sk_abc123_secretXYZ" \
  https://api.biterp.ai/products

# Ou diretamente
curl -H "Authorization: sk_abc123_secretXYZ" \
  https://api.biterp.ai/products

Características

Propriedade	Descrição
Escopo	Cada key pertence a um único tenant
Permissões	Granulares por recurso e ação (imutáveis após criação)
Expiração	Opcional — campo `expires_at` configurável
Segurança	Hash SHA-256 do secret (nunca armazenado em texto)
Revogação	Soft delete — a key pode ser revogada a qualquer momento

Criando uma API Key

Acesse Configurações > API Keys no painel do bitERP
Clique em Criar API Key
Defina nome, descrição e permissões
Copie o token exibido

Exemplo de payload de criação:

{
    "name": "ERP Integration",
    "description": "Integração com sistema ERP externo",
    "permissions": [
        { "resource_code": "products", "can_read": true, "can_create": true },
        { "resource_code": "customers", "can_read": true },
        { "resource_code": "invoices", "can_read": true, "can_create": true }
    ],
    "expires_at": "2026-12-31"
}

OAuth2 Authorization Code

Para integrações via plataformas como Zapier, Make e n8n, a API suporta o fluxo OAuth2 Authorization Code com PKCE (S256).

Endpoints OAuth

Método	Endpoint	Descrição
`GET`	`/.well-known/oauth-authorization-server`	Metadata do servidor OAuth (RFC 8414)
`GET`	`/oauth/authorize`	Inicia o fluxo de autorização
`POST`	`/oauth/token`	Troca code por access token
`POST`	`/oauth/revoke`	Revoga um token
`GET`	`/oauth/userinfo`	Retorna dados do usuário autenticado

Fluxo de autorização

1. Sua app redireciona o usuário para /oauth/authorize
   com client_id, redirect_uri, scope, state, code_challenge

2. Usuário autentica e autoriza no painel bitERP

3. bitERP redireciona de volta com authorization code

4. Sua app troca o code em POST /oauth/token
   com client_id + client_secret

5. Usa o access token (bit_*) para chamar a API

Formato dos tokens OAuth

Token	Prefixo	Descrição
Access token	`bit_`	Token de acesso para chamadas à API
Refresh token	`bitrf_`	Token para renovar o access token
Authorization code	`bitac_`	Código temporário para troca por tokens

Rate limits OAuth

Endpoint	Limite
`GET /oauth/authorize`	20 req/min por IP
`POST /oauth/token`	10 req/min por `client_id`

Níveis de acesso OAuth

Role	Acesso
`admin`	Acesso completo a todos os recursos
`member`	Acesso limitado conforme permissões granulares

Usuários com role member só acessam endpoints para os quais possuem permissão configurada. Recursos marcados como is_admin_only são restritos a usuários admin.

Autenticação

Nesta página