A API Base39 utiliza chaves de API para autenticar requisições. Use a chave no header Authorization em todas as requisições.

Se uma solicitação não incluir uma chave válida, a Base39 retornará um erro de solicitação inválida.

Se uma solicitação incluir uma chave excluída ou expirada, a Base39 retornará um erro de autenticação.

Utilize os seguintes endpoints para criar, revogar, atualizar e listar suas chaves de API:

• Listar chaves de API
• Criar chave de API
• Atualizar chave da API
• Revogar chave da API

Criação de chaves de API

Para restringir o acesso aos recursos, a Base39 disponibiliza a possibilidade de criação de chaves de API através do enpoint: Criar chave da api.

Confira abaixo um exemplo de configuração de criação de chave de API:

{
  "name": "teste",
  "email": "[email protected]",
  "rules": [
    {
      "resource": "/v1/loans",
      "rule": "readOnly"
    }
  ],
  "allowedIps": [
    {
      "ip": "200.50.0.0/10",
      "description": "Ips allowed"
    }
  ]
}

Chave	Descrição
name	Nome do desenvolvedor responsável.
email	Email do desenvolvedor responsável.
rules	A regra que será aplicada ao recurso descrito. As regras disponíveis são: readOnly(apenas leitura), readWrite(leitura e escrita), writeOnly(apenas escrita).
allowedIps	Regra para definir IPs específicos para utilizar a chave.
isFineGrained	Utilizado para ativar ou desativar o controle de acesso granular. Quando habilitado (true), são aplicadas regras detalhadas definidas pelo autorizador para permitir ou negar o acesso a recursos específicos com base em condições predefinidas.

Granulação de chaves de API

A granulação de chaves de API refere-se ao nível de controle e especificidade com que as permissões e acessos são configurados para essas chaves. Esse controle pode variar desde uma abordagem ampla até um nível extremamente detalhado.

Para configurar a granulação, é necessário definir em rules o atributo conditions.

Chave	Descrição
field	Campo que será utilizado para verificar se a chave terá os campos definidos em allowedValues
searchIn	Parâmetro que será utilizado para realizar a busca. Atualmente só é possível utilizar 3 chaves: body, query e path
allowedValues	Valores que serão aceitos no campo de referência.

Para que uma condição seja validada é necessário que pelo menos um dos valores definidos em allowedValues seja validado.

nota

É permitida apenas uma regra por recurso, mas um recurso pode ter várias condições. Todas as condições devem ser validadas para que o acesso seja autorizado.

Exemplo de configuração com query

{
  "name": "teste",
  "email": "[email protected]",
  "isFineGrained": true,
  "rules": [
    {
      "conditions": [
        {
          "field": "company",
          "searchIn": "query",
          "allowedValues": ["comp_6386073a3115943556b99fea"]
        }
      ],
      "resource": "/v1/loans",
      "rule": "readOnly"
    }
  ]
}

A chave retornada funcionará apenas para a rota especificada em resource. Para que a chave seja válida, a rota deve conter no parâmetro de query o campo company com pelo menos um dos valores listados em allowedValues.

Exemplo de como ficaria a rota:

- GET v1/loans?company=comp_667319ee5068398b6e032d70

Exemplo de configuração de criação de chave com path

{
  "name": "teste",
  "email": "[email protected]",
  "isFineGrained": true,
  "rules": [
    {
      "conditions": [
        {
          "field": "id",
          "searchIn": "path",
          "allowedValues": ["comp_667319ee5068398b6e032d70"]
        }
      ],
      "resource": "/v1/companies/*",
      "rule": "readOnly"
    }
  ]
}

A chave retornada funcionará apenas para rota especificada em resource, desde que nos parâmetros de rota o campo id contenha pelo menos um dos valores especificados em allowedValues.

Exemplo de como ficaria a rota:

- GET v1/companies/comp_667319ee5068398b6e032d70

Exemplo de configuração de criação de chave com body

{
  "name": "teste",
  "email": "[email protected]",
  "isFineGrained": true,
  "rules": [
    {
      "conditions": [
        {
          "field": "metadata.chave",
          "searchIn": "body",
          "allowedValues": ["valor"]
        }
      ],
      "resource": "/v1/company-groups",
      "rule": "writeOnly"
    }
  ]
}

A chave retornada funcionará apenas para a rota especificada em resource, desde que o campo metadata.chave no corpo da requisição (body) contenha exatamente o valor definido em allowedValues.

Exemplo de como ficaria a rota:

- POST v1/company-groups

Sandbox vs Produção

Todas as requisições da API Base39 ocorrem em ambiente de produção ou sandbox.

Use o modo sandbox para acessar dados de teste e o modo de produção para acessar os dados reais do seu tenant.

Tipo	Quando usar	Objetos	Considerações
Sandbox	Use as chaves sandbox quando estiver construindo suas integrações. Nesse modo, nenhuma trasação financeira é executada.	Requisições da API retornam objetos simulados. Por exemplo, você deve visualizar company, employment, customer, fund, product, operator e permission.	Algumas integrações de terceiros podem exigir algum documento. Consulte a documentação dos parceiros sobre limitações dos ambientes de teste.
Produção	Use as chaves produção quando você estiver pronto para executar uma ação real. Transações financeiras serão executadas.	Requisições da API retornam valores reais.	Integrações de terceiro podem exigir homolagações antes de liberar o ambiente de produção.