> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwify.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conta de Serviço

> Como criar e gerenciar contas de serviço no dashboard Conta Digital

# Conta de Serviço

Contas de serviço permitem que sua aplicação acesse a Banking API de forma programática. Cada conta de serviço possui:

* **Access ID** - Identificador único (UUID)
* **Chave Pública** - Para verificar assinaturas
* **Permissões** - Controle granular de acesso
* **IPs Permitidos** - Lista de IPs autorizados

## Criando uma Conta de Serviço

### 1. Acesse o Dashboard

Navegue até **Configurações** → **Credenciais API** no [dashboard Conta Digital](https://dashboard.kiwify.com.br).

### 2. Clique em "Nova Credencial"

Preencha os campos:

| Campo              | Descrição                                                                   |
| ------------------ | --------------------------------------------------------------------------- |
| **Descrição**      | Nome para identificar a credencial (ex: "Backend Produção")                 |
| **Chave Pública**  | Sua chave Ed25519 no formato `ssh-ed25519 ...`                              |
| **Permissões**     | Selecione as permissões necessárias                                         |
| **IPs Permitidos** | Lista de IPs ou CIDRs autorizados *(opcional, padrão: `0.0.0.0/0`, `::/0`)* |

### 3. Salve o Access ID

Após criar, você receberá um **Access ID** (UUID). Este é o valor do header `x-access-id` nas requisições.

<Warning>
  O Access ID é exibido apenas uma vez. Copie e guarde em local seguro.
</Warning>

## Permissões Disponíveis

| Permissão                   | Descrição             | Endpoints                                           |
| --------------------------- | --------------------- | --------------------------------------------------- |
| `view_balance`              | Ver saldo             | `GET /v1/balance`                                   |
| `view_account_details`      | Ver detalhes da conta | `GET /v1/account`, `GET /v1/account-limits`         |
| `view_transactions`         | Ver transações        | `GET /v1/transactions`, `GET /v1/transactions/{id}` |
| `list_dict_keys`            | Listar chaves PIX     | `GET /v1/dict-keys`                                 |
| `initiate_payment`          | Criar transferências  | `POST /v1/transfers`                                |
| `cancel_scheduled_payments` | Cancelar pagamentos   | Pagamentos agendados                                |
| `refund_transaction`        | Estornar transações   | Estornos                                            |

<Note>
  Aplique o princípio do menor privilégio. Conceda apenas as permissões necessárias para sua aplicação.
</Note>

## IPs Permitidos

Configure uma lista de IPs autorizados para maior segurança. Formatos aceitos:

```
192.168.1.100        # IP único
192.168.1.0/24       # Range CIDR
2001:db8::1          # IPv6
```

Se nenhum IP for configurado, requisições de qualquer IP serão aceitas (`0.0.0.0/0` e `::/0`).

## Gerenciando Contas de Serviço

### Listar Contas

No dashboard, veja todas as contas de serviço ativas com:

* Descrição
* Access ID (parcialmente oculto)
* Permissões
* IPs permitidos

### Excluir Conta

Para revogar acesso, exclua a conta de serviço. A exclusão é imediata e permanente.

<Warning>
  Após excluir, todas as requisições usando aquele Access ID serão rejeitadas com `401 Unauthorized`.
</Warning>

## Fluxo Completo

<Steps>
  <Step title="Gerar Chaves">
    Crie um par de chaves Ed25519 usando `ssh-keygen` ou outro método.
    [Ver instruções →](/api-reference/banking/key-generation)
  </Step>

  <Step title="Criar Conta de Serviço">
    No dashboard, cadastre a chave pública e configure permissões.
  </Step>

  <Step title="Guardar Credenciais">
    Salve o Access ID e a chave privada em local seguro (variáveis de ambiente, secret manager).
  </Step>

  <Step title="Fazer Requisições">
    Use a chave privada para assinar requisições.
    [Ver autenticação →](/api-reference/banking/authentication)
  </Step>
</Steps>

## Boas Práticas

<CardGroup cols={2}>
  <Card title="Rotacione Periodicamente" icon="arrows-rotate">
    Crie novas credenciais regularmente e revogue as antigas.
  </Card>

  <Card title="Ambiente Separado" icon="code-branch">
    Use contas de serviço diferentes para dev, staging e produção.
  </Card>

  <Card title="Permissões Mínimas" icon="shield">
    Conceda apenas as permissões estritamente necessárias.
  </Card>

  <Card title="Restrinja IPs" icon="network-wired">
    Configure IPs permitidos para seus servidores de produção.
  </Card>
</CardGroup>