> ## 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.

# Service Accounts

> How to create and manage service accounts in the Conta Digital dashboard

# Service Accounts

Service accounts allow your application to access the Banking API programmatically. Each service account has:

* **Access ID** - Unique identifier (UUID)
* **Public Key** - For signature verification
* **Permissions** - Granular access control
* **Allowed IPs** - List of authorized IPs

## Creating a Service Account

### 1. Access the Dashboard

Navigate to **Settings** → **API Credentials** in the [Conta Digital dashboard](https://dashboard.kiwify.com.br).

### 2. Click "New Credential"

Fill in the fields:

| Field           | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| **Description** | Name to identify the credential (e.g., "Production Backend")               |
| **Public Key**  | Your Ed25519 key in `ssh-ed25519 ...` format                               |
| **Permissions** | Select the required permissions                                            |
| **Allowed IPs** | List of authorized IPs or CIDRs *(optional, default: `0.0.0.0/0`, `::/0`)* |

### 3. Save the Access ID

After creation, you'll receive an **Access ID** (UUID). This is the value for the `x-access-id` header in requests.

<Warning>
  The Access ID is shown only once. Copy and store it securely.
</Warning>

## Available Permissions

| Permission                  | Description          | Endpoints                                           |
| --------------------------- | -------------------- | --------------------------------------------------- |
| `view_balance`              | View balance         | `GET /v1/balance`                                   |
| `view_account_details`      | View account details | `GET /v1/account`, `GET /v1/account-limits`         |
| `view_transactions`         | View transactions    | `GET /v1/transactions`, `GET /v1/transactions/{id}` |
| `list_dict_keys`            | List PIX keys        | `GET /v1/dict-keys`                                 |
| `initiate_payment`          | Create transfers     | `POST /v1/transfers`                                |
| `cancel_scheduled_payments` | Cancel payments      | Scheduled payments                                  |
| `refund_transaction`        | Refund transactions  | Refunds                                             |

<Note>
  Apply the principle of least privilege. Grant only the permissions your application needs.
</Note>

## Allowed IPs

Configure a list of authorized IPs for added security. Accepted formats:

```
192.168.1.100        # Single IP
192.168.1.0/24       # CIDR range
2001:db8::1          # IPv6
```

If no IPs are configured, requests from any IP will be accepted (`0.0.0.0/0` and `::/0`).

## Managing Service Accounts

### List Accounts

In the dashboard, view all active service accounts with:

* Description
* Access ID (partially hidden)
* Permissions
* Allowed IPs

### Delete Account

To revoke access, delete the service account. Deletion is immediate and permanent.

<Warning>
  After deletion, all requests using that Access ID will be rejected with `401 Unauthorized`.
</Warning>

## Complete Flow

<Steps>
  <Step title="Generate Keys">
    Create an Ed25519 keypair using `ssh-keygen` or another method.
    [See instructions →](/api-reference/banking/key-generation)
  </Step>

  <Step title="Create Service Account">
    In the dashboard, register the public key and configure permissions.
  </Step>

  <Step title="Store Credentials">
    Save the Access ID and private key securely (environment variables, secret manager).
  </Step>

  <Step title="Make Requests">
    Use the private key to sign requests.
    [See authentication →](/api-reference/banking/authentication)
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Rotate Regularly" icon="arrows-rotate">
    Create new credentials periodically and revoke old ones.
  </Card>

  <Card title="Separate Environments" icon="code-branch">
    Use different service accounts for dev, staging, and production.
  </Card>

  <Card title="Minimal Permissions" icon="shield">
    Grant only the strictly necessary permissions.
  </Card>

  <Card title="Restrict IPs" icon="network-wired">
    Configure allowed IPs for your production servers.
  </Card>
</CardGroup>