AuthDuty API

Quick Start

Authentication

All API requests require a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer ad_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys start with ad_live_. Keep them secret - treat them like passwords. Revoke compromised keys immediately in the console.

Code Examples

curl -X POST https://api.authduty.com/v1/cases/ \
  -H "Authorization: Bearer ad_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "subject_email": "[email protected]",
    "verification_methods": {
      "email": true,
      "government_id": true
    },
    "notes": "New hire verification"
  }'

import uuid
import requests

API_KEY = "ad_live_YOUR_API_KEY"

resp = requests.post(
    "https://api.authduty.com/v1/cases/",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "subject_email": "[email protected]",
        "verification_methods": {
            "email": True,
            "government_id": True,
        },
        "notes": "New hire verification",
    },
)

case = resp.json()
print(f"Verification URL: {case['verification_url']}")

const API_KEY = "ad_live_YOUR_API_KEY";

const resp = await fetch("https://api.authduty.com/v1/cases/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    subject_email: "[email protected]",
    verification_methods: {
      email: true,
      government_id: true,
    },
    notes: "New hire verification",
  }),
});

const caseData = await resp.json();
console.log(`Verification URL: ${caseData.verification_url}`);

require "net/http"
require "json"
require "securerandom"

API_KEY = "ad_live_YOUR_API_KEY"

uri = URI("https://api.authduty.com/v1/cases/")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = SecureRandom.uuid
req.body = {
  subject_email: "[email protected]",
  verification_methods: {
    email: true,
    government_id: true
  },
  notes: "New hire verification"
}.to_json

resp = http.request(req)
case_data = JSON.parse(resp.body)
puts "Verification URL: #{case_data['verification_url']}"

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/google/uuid"
)

func main() {
    apiKey := "ad_live_YOUR_API_KEY"

    body, _ := json.Marshal(map[string]interface{}{
        "subject_email": "[email protected]",
        "verification_methods": map[string]bool{
            "email":         true,
            "government_id": true,
        },
        "notes": "New hire verification",
    })

    req, _ := http.NewRequest("POST",
        "https://api.authduty.com/v1/cases/", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Idempotency-Key", uuid.NewString())

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Verification URL: %s\n", result["verification_url"])
}

Endpoints

Verification Methods

Each case requires at least one verification method. Pass the desired methods in the verification_methods object when creating a case.

Case Lifecycle

Cases expire 48 hours after creation. The response includes expires_at (ISO 8601) and is_expired (boolean).

• closed - all verification steps completed successfully
• failed - a verification step was rejected (e.g. ID check)
• expired - 48-hour window elapsed before completion

Pagination

List endpoints use cursor-based pagination, returning 50 results per page ordered by newest first. Applies to GET /v1/cases/ and GET /v1/webhooks/deliveries/.

Response Envelope

{
  "next": "https://api.authduty.com/v1/cases/?cursor=cD0yMDI2...",
  "previous": null,
  "results": [
    { "id": "550e8400-...", "status": "open", "..." : "..." }
  ]
}

Follow the next URL to fetch subsequent pages. When next is null, you've reached the end.

# Fetch the first page
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.authduty.com/v1/cases/"

# Follow the "next" URL for subsequent pages
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.authduty.com/v1/cases/?cursor=cD0yMDI2..."

url = "https://api.authduty.com/v1/cases/"
all_cases = []

while url:
    resp = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"})
    data = resp.json()
    all_cases.extend(data["results"])
    url = data["next"]

let url = "https://api.authduty.com/v1/cases/";
const allCases = [];

while (url) {
  const resp = await fetch(url, {
    headers: { "Authorization": `Bearer ${API_KEY}` },
  });
  const data = await resp.json();
  allCases.push(...data.results);
  url = data.next;
}

url = URI("https://api.authduty.com/v1/cases/")
all_cases = []

while url
  req = Net::HTTP::Get.new(url)
  req["Authorization"] = "Bearer #{API_KEY}"
  resp = Net::HTTP.start(url.host, url.port, use_ssl: true) { |h| h.request(req) }
  data = JSON.parse(resp.body)
  all_cases.concat(data["results"])
  url = data["next"] ? URI(data["next"]) : nil
end

url := "https://api.authduty.com/v1/cases/"

for url != "" {
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    resp, _ := http.DefaultClient.Do(req)

    var page struct {
        Next    *string                  `json:"next"`
        Results []map[string]interface{} `json:"results"`
    }
    json.NewDecoder(resp.Body).Decode(&page)
    resp.Body.Close()

    // process page.Results ...

    if page.Next != nil {
        url = *page.Next
    } else {
        url = ""
    }
}

Filtering

List endpoints accept optional query parameters to filter results. All filters are combinable and preserved across paginated responses.

Cases

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.authduty.com/v1/cases/?status=open&created_after=2026-01-01T00:00:00Z"

Deliveries

Response Schemas

Case

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "public_id": "a1b2c3d4",
  "status": "open",
  "subject_email": "[email protected]",
  "subject_name": null,
  "created_at": "2026-03-23T12:00:00Z",
  "expires_at": "2026-03-25T12:00:00Z",
  "is_expired": false,
  "verification_url": "https://verify.authduty.com/v/a1b2c3d4",
  "verification_methods": {
    "email": { "requested": true, "verified": false },
    "government_id": { "requested": true, "verified": false },
    "selfie": { "requested": true, "verified": false }
  },
  "notes": "New hire verification"
}

Account

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Acme Widgets Inc.",
  "plan": "starter",
  "subscription_status": "active",
  "topup_balance_cents": 2500,
  "created_at": "2025-11-01T09:00:00Z"
}

Usage

{
  "billing_period_start": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-04-01T00:00:00Z",
  "usage": {
    "email": {
      "allowed": 100, "included_used": 12, "topup_used": 0,
      "topup_cost_cents": 0, "total_used": 12, "percent_used": 12.0
    },
    "sms": {
      "allowed": 50, "included_used": 3, "topup_used": 0,
      "topup_cost_cents": 0, "total_used": 3, "percent_used": 6.0
    }
  }
}

Error Codes

All errors return a JSON body with error, detail, and code fields:

{
  "error": "insufficient_allowance",
  "detail": "SMS allowance exhausted and insufficient top-up balance.",
  "code": "INSUFFICIENT_ALLOWANCE"
}

Webhooks

AuthDuty sends webhook notifications to your HTTPS endpoints when events occur. Each delivery is signed with HMAC-SHA256 and retried with exponential backoff on failure.

Rate Limits

When rate limited, the response includes a Retry-After header with the number of seconds until the next allowed request.

Versioning

All API paths are prefixed with /v1/. Breaking changes will be introduced under a new version prefix. Non-breaking additions (new fields, new endpoints) may extend v1.

Changelog

• v1 - Initial release