Secret keys — Dakio developer docs

Everything a storefront needs works with a client key and no server. A secret key (dk_sec_live_…) adds what needs one: the store's order list, webhook management, and checkout from a server. Create it in Settings → Developers → Secret keys; Dakio shows it once.

// server only — an API route, a server action, a worker
import { createDakio } from '@dakio/sdk'
const dakio = createDakio({ key: process.env.DAKIO_SECRET_KEY })

Server only

Never put a secret key in browser code or an environment variable starting with NEXT_PUBLIC_. createDakio refuses one in a browser, and Dakio refuses any request carrying one with a browser Origin (SECRET_KEY_IN_BROWSER). If it leaks, revoke it in Settings → Developers.

A secret key can do everything a client key can, plus the following.

Read orders

const page = await dakio.orders.list({ limit: 50 })                       // newest first
const sync = await dakio.orders.list({ updatedSince: lastSyncAt })        // oldest change first
const one  = await dakio.orders.get('ABC-1234')                           // or an id; null if none

Every order in the store, wherever it came from: your website, the Dakio store, Nova in the inbox, POS, or entered by hand. Filters: page, limit (up to 100), createdSince, updatedSince, phone.

Field	What it is
id, orderNumber	Identity
status, statusLabel	placed → confirmed → preparing → shipped → on_the_way → out_for_delivery → delivered, or cancelled / returned
customer	{ name, phone, email, address, city, district }
items	[{ productId, variantId, name, sku, qty, unitPrice, total }]
subtotal, shipping, discount, total, paid, due	Taka
codAmount, paymentMethod	What the courier collects; 'COD'
courier	{ provider, trackingCode } once booked
source	{ channel, apiKeyId } — website_sdk, storefront, or null for orders made inside Dakio
placedAt, updatedAt	ISO dates

To sync, store the largest updatedAt you've seen and pass it as updatedSince next time — or skip polling and use webhooks. Orders are read-only through the API; confirming, shipping and cancelling happen in Dakio.

Checkout from a server

Dakio's fake-order protection judges the buyer's IP. From a server, say who the buyer is:

// a Next.js server action
'use server'
import { headers } from 'next/headers'

export async function placeOrder(input) {
  const h = await headers()
  return dakio.checkout.create(input, {
    buyer: { ip: h.get('x-forwarded-for') ?? '', userAgent: h.get('user-agent') },
  })
}

The SDK sends it as Dakio-Buyer-Ip (the first address in a forwarded list) and Dakio-Buyer-Agent. Dakio trusts those headers only from a secret key — anyone can set a header, and a client key sits in public code. From a server they're required for checkout, the code step, abandoned carts and "my orders": without them you get BUYER_IP_REQUIRED, because every shopper would otherwise be judged as your one server.

await dakio.checkout.verifyOtp({ sessionToken, otp }, { buyer })
await dakio.leads.capture(lead, { buyer })
await dakio.account.sendCode(phone, { buyer })

Pass the real visitor's address. Behind Vercel, Netlify or Cloudflare it's in x-forwarded-for (or cf-connecting-ip); behind your own proxy, make sure it sets one.

Manage webhooks

The same list as Settings → Developers → Webhooks, with a live secret key:

const hook = await dakio.webhooks.create({ url: 'https://mybrand.com.bd/api/dakio', events: ['order.created'] })
hook.secret            // whsec_… — shown here once
await dakio.webhooks.list()
await dakio.webhooks.delete(hook.id)

Test secret keys

dk_sec_test_… places test orders and orders.list returns test orders, like a client test key. Webhooks need a live key: they carry real orders.