Docs › Getting started

Authentication

Bearer API keys and HMAC-signed requests.

Every /v1/orders and /v1/webhooks call is authenticated with your API key. Pick one of two styles per request.

Bearer key (recommended)

http

Authorization: Bearer dfk_live_8c1f…

bash

curl -s https://api.trydragonfly.com/v1/orders/order-1001 -H "Authorization: Bearer $DRAGONFLY_API_KEY"

HMAC-signed requests

To avoid sending the key on every request, sign the raw request body with your signing secret instead:

Header	Value
`X-Dragonfly-Key`	Your key prefix: the first 16 characters of the key, e.g. `dfk_live_8c1f2a3`
`X-Dragonfly-Signature`	Lowercase hex HMAC-SHA256 of the exact raw body, keyed with your signing secret

bash

BODY='{"externalId":"order-1002","pickup":{...},"dropoff":{...}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$DRAGONFLY_SIGNING_SECRET" | awk '{print $NF}')
curl -s https://api.trydragonfly.com/v1/orders \
  -H "X-Dragonfly-Key: ${DRAGONFLY_API_KEY:0:16}" -H "X-Dragonfly-Signature: $SIG" \
  -H 'content-type: application/json' -d "$BODY"

javascript

import crypto from 'node:crypto'
const body = JSON.stringify(order)
const signature = crypto.createHmac('sha256', process.env.DRAGONFLY_SIGNING_SECRET).update(body).digest('hex')
await fetch('https://api.trydragonfly.com/v1/orders', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'X-Dragonfly-Key': process.env.DRAGONFLY_API_KEY.slice(0, 16), 'X-Dragonfly-Signature': signature },
  body,
})

Important: sign the bytes you send. Re-serializing the JSON after signing (key order, whitespace) breaks the signature.

Scopes

Keys are issued with orders:write and orders:read. orders:write also satisfies reads. A key without the required scope gets 403 FORBIDDEN.

Keeping keys safe

Keep keys server-side. Never put them in a browser, mobile app or public repo.
Use one key per system or agent, with a clear label, so you can revoke one without breaking the others.
Rotate by creating a new key, deploying it, then revoking the old one.

← PreviousGetting access & approval Next →Sandbox vs. production

Something unclear or missing? Tell us.