API Keys

API keys (Developer Keys) are used to authenticate server-to-server API requests. This guide covers generating, managing, and securing your API keys.

Overview

Dimebia uses secret keys (SK) for API authentication. Each key has:

• Scope: Permissions defining what the key can access
• State: Active or revoked
• Owner: The user who created the key

Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• sk_live_: Prefix indicating a live/production key
• 32 random characters: The secret key portion

Generate an API Key

POST /api/developer/mine/generate

Request Body

Field	Type	Required	Description
scope	String	No	Comma-separated list of permissions

Default Scopes

If no scope is specified, the following scopes are granted:

• transaction_write - Create transactions
• transaction_read - Read transactions
• user_write - Create/update users
• user_read - Read user information

Available Scopes

Scope	Description
transaction_write	Create and update transactions
transaction_read	Read transaction data
transaction_refund	Process refunds
user_write	Create and update users
user_read	Read user data
channel_read	Read channel configurations
channel_write	Modify channels
invoice_read	Read invoices
invoice_write	Create/update invoices
subscription_read	Read subscriptions
subscription_write	Modify subscriptions
*	All permissions (admin only)

Example

curl -X POST http://localhost:8080/api/developer/mine/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "scope": "transaction_write,transaction_read"
  }'

Response

{
  "code": 200,
  "message": "Developer key generated",
  "data": {
    "id": 1,
    "sk": "sk_live_abcdefghijklmnopqrstuvwxyz0123456789",
    "scope": "transaction_write,transaction_read",
    "state": 1,
    "createdTime": "2026-08-18T10:00:00Z"
  }
}

Important: The full sk is only shown once. Store it securely.

List Your Keys

GET /api/developer/mine

Response shows masked keys for security:

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "skMasked": "abcd...xyz9",
      "scope": "transaction_write,transaction_read",
      "state": 1,
      "createdTime": "2026-08-18T10:00:00Z",
      "updatedTime": null
    }
  ]
}

Revoke a Key

POST /api/developer/mine/revoke

{
  "id": 1
}

Revocation is immediate and cannot be undone. The key will no longer work for API authentication.

Using API Keys

Include the key in the Authorization header:

curl -X POST http://localhost:8080/api/transaction/create \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey sk_live_abcdefghijklmnopqrstuvwxyz0123456789" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "channelId": 1
  }'

Security Best Practices

1. Never expose keys in client-side code (browsers, mobile apps)
2. Use environment variables to store keys
3. Rotate keys regularly (recommended: every 90 days)
4. Use minimal scopes - only grant necessary permissions
5. Revoke unused keys immediately
6. Monitor key usage through audit logs

Key Permissions Matrix

Endpoint	transaction_read	transaction_write	transaction_refund
GET /api/transaction/list	✅
POST /api/transaction/create		✅
POST /api/refund/create			✅