HonkIO Auth

Plan and usage

Read and change an app’s plan, cancel a scheduled downgrade, and read its sign-in costs by method and its user count.

Get the plan

GET/v1/auth-apps/:id/plan

Permission: auth_apps: r

The app’s plan, billing state, current period and any scheduled change.

Request

curl https://api.honkio.ca/v1/auth-apps/APP_ID/plan \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

Response · 200

{
  "plan": "pro",
  "mode": "live",
  "currency": "CAD",
  "price_cents": 4900,
  "included_users": 2500,
  "overage_cents_per_user": 2.5,
  "features": {
    "email_sign_in": true,
    "passkeys": true,
    "custom_domain": true,
    "webhooks": true,
    "texts": true,
    "two_step": true,
    "organizations": false,
    "two_step_per_org_role": false,
    "voip_blocking": true
  },
  "billing": {
    "state": "ok",
    "grace_started_at": null,
    "grace_ends_at": null,
    "absorb_until": null,
    "unpaid_cents": 0,
    "sign_ups_allowed": true,
    "texts_allowed": true
  },
  "period": {
    "start": "2026-11-01T05:00:00.000Z",
    "end": "2026-12-01T05:00:00.000Z",
    "fee_cents": 4900,
    "fee_status": "charged",
    "active_users": 812
  },
  "scheduled_change": null,
  "warnings": []
}

Change the plan

PUT/v1/auth-apps/:id/plan

Permission: auth_apps: m

Moves the app to another plan. A downgrade is scheduled for the end of the cycle, and the response lists what will turn off.

Body

Name	Type	Description
planrequired	"free" \| "pro" \| "business"	The plan to move to.
dry_run	boolean	Preview the change and its cost without making it.

Request

curl -X PUT https://api.honkio.ca/v1/auth-apps/APP_ID/plan \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "free"
  }'

Response · 200

{
  "plan": "pro",
  "change": {
    "kind": "downgrade",
    "from": "pro",
    "to": "free",
    "effective_at": "2026-12-01T05:00:00.000Z",
    "scheduled": true,
    "charged_cents": 0,
    "dry_run": false,
    "cancelled_scheduled_change": false
  },
  "turns_off": [
    "texts",
    "two_step",
    "voip_blocking"
  ],
  "impact": {
    "turns_off": [
      "texts",
      "two_step",
      "voip_blocking"
    ],
    "users_total": 1240,
    "effects": [
      {
        "code": "texts_off",
        "users_with_phone": 310,
        "users_without_email": 12
      },
      {
        "code": "two_step_off",
        "app_requires_two_step": false
      }
    ]
  }
}

Cancel a scheduled downgrade

DELETE/v1/auth-apps/:id/plan/scheduled

Permission: auth_apps: d

Keeps the current plan.

Request

curl -X DELETE https://api.honkio.ca/v1/auth-apps/APP_ID/plan/scheduled \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

204 · No content.

Get sign-in costs

GET/v1/auth-apps/:id/costs

Permission: auth_apps: r

Sign-in message costs for a month, by method: email, text, and passkey (always 0).

Query parameters

Name	Type	Description
month	YYYY-MM	The month, such as `2026-11`. The current month by default.

Request

curl https://api.honkio.ca/v1/auth-apps/APP_ID/costs?month=2026-11 \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

Response · 200

{
  "month": "2026-11",
  "currency": "CAD",
  "methods": [
    {
      "method": "email",
      "messages": 4120,
      "cost_cents": 4.12,
      "absorbed_messages": 0,
      "comped_messages": 0
    },
    {
      "method": "text",
      "messages": 310,
      "segments": 312,
      "cost_cents": 1023,
      "absorbed_messages": 0,
      "comped_messages": 0
    },
    {
      "method": "passkey",
      "messages": 0,
      "cost_cents": 0,
      "absorbed_messages": 0,
      "comped_messages": 0
    }
  ],
  "plan_fee_cents": 4900,
  "overage_cents": 0,
  "total_cents": 5927.12
}

Get usage

GET/v1/auth-apps/:id/usage

Permission: auth_apps: r

Counted users this month against the plan’s included users.

Request

curl https://api.honkio.ca/v1/auth-apps/APP_ID/usage \
  -H "Authorization: Bearer mk_test_YOUR_KEY"

Response · 200

{
  "plan": "pro",
  "period_start": "2026-11-01T05:00:00.000Z",
  "period_end": "2026-12-01T05:00:00.000Z",
  "active_users": 812,
  "included_users": 2500,
  "percent_used": 32,
  "overage_users": 0,
  "estimated_overage_cents": 0,
  "sign_ups_paused": false,
  "billing_state": "ok",
  "total_users": 1240,
  "likely_bots": 3,
  "activity_since": "2026-11-01T05:00:00.000Z",
  "sign_ins": 2140,
  "signed_in_users": 905,
  "has_signed_in": true,
  "warnings": []
}