Skip to main content

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

​
2. Click “New Credential”

Fill in the fields:
FieldDescription
DescriptionName to identify the credential (e.g., “Production Backend”)
Public KeyYour Ed25519 key in ssh-ed25519 ... format
PermissionsSelect the required permissions
Allowed IPsList 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.
The Access ID is shown only once. Copy and store it securely.

​
Available Permissions

PermissionDescriptionEndpoints
view_balanceView balanceGET /v1/balance
view_account_detailsView account detailsGET /v1/account, GET /v1/account-limits
view_transactionsView transactionsGET /v1/transactions, GET /v1/transactions/{id}
list_dict_keysList PIX keysGET /v1/dict-keys
initiate_paymentCreate transfersPOST /v1/transfers
cancel_scheduled_paymentsCancel paymentsScheduled payments
refund_transactionRefund transactionsRefunds
Apply the principle of least privilege. Grant only the permissions your application needs.

​
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.
After deletion, all requests using that Access ID will be rejected with 401 Unauthorized.

​
Complete Flow

1

Generate Keys

Create an Ed25519 keypair using ssh-keygen or another method. See instructions →
2

Create Service Account

In the dashboard, register the public key and configure permissions.
3

Store Credentials

Save the Access ID and private key securely (environment variables, secret manager).
4

Make Requests

Use the private key to sign requests. See authentication →

​
Best Practices

Rotate Regularly

Create new credentials periodically and revoke old ones.

Separate Environments

Use different service accounts for dev, staging, and production.

Minimal Permissions

Grant only the strictly necessary permissions.

Restrict IPs

Configure allowed IPs for your production servers.