Chaves de API
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:
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": "test@test.com",
"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 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.
É 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": "test@test.com",
"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": "test@test.com",
"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": "test@test.com",
"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. |