aria-partner-api

Partner endpoint

Production base URL: https://my.kanary.com/api/v1/

Partner records are provisioned when you set up your organization via the admin dashboard.

Method Path Purpose
GET /api/v1/ Retrieve the authenticated partner
GET /api/v1/seats/ Seat inventory per subscription (Seat inventory)
POST /api/v1/seats/ Purchase subscription seats (Purchase seats)
GET /api/v1/credits/ Unassigned on-demand credits (Credit pool)
POST /api/v1/credits/ Buy unassigned on-demand credits (Purchase credits)

On-demand scans spend credits assigned to the member: POST /api/v1/scan/. Those balances are on Scan credits.

Auth: Bearer token required. See Authentication. Account directory and members: Account API.

Partner object

Returned only by GET /api/v1/.

Field Type Description
id integer Partner primary key
name string Display / organization name
created_at string When the partner record was created (timestamps)
domain_name string | null Primary email domain for enrollment matching
active boolean Whether the partner organization is fully activated for API use
has_payment_method boolean true when the partner has a payment method on file for seat and product charges

Timestamps

created_at and other datetimes are UTC, ISO 8601: YYYY-MM-DDTHH:MM:SS[.ffffff]+00:00.

"created_at": "2025-06-01T08:00:00.123456+00:00"

Retrieve partner (current session)

GET /api/v1/

Returns the partner linked to your API key.

Auth: Partner API key. See Authentication.

Success (200 OK)

Returns the partner object at the top level.

{
  "id": 42,
  "name": "Waystar Roy Security & Company",
  "created_at": "2025-06-01T08:00:00.123456+00:00",
  "domain_name": "acme.com",
  "active": true,
  "has_payment_method": true
}

Errors

Status Condition
401 Missing or invalid bearer token
403 Authenticated user is not linked to a partner, or partner is not active

Seat inventory

GET /api/v1/seats/

Seats are products with charge_type "subscription". This inventory is subscriptions only. Unassigned on-demand credits are on GET /api/v1/credits/. Credits assigned to a member are on GET /api/v1/members/{member_id}/credits/. Product names, descriptions, and billing are on GET /api/v1/products/.

Pass a subscription product_id on POST /api/v1/accounts/. Link an on-demand scan with POST .../product/; that call draws from the credit pool.

POST /api/v1/members/{member_id}/change_subscription/{new_product_id}/ moves the member’s existing seat to another subscription product_id. An upgrade from Core to Advanced is charged on the partner payment method at the time of the change. The history is on GET .../subscriptions/{product_id}/.

Success (200 OK)

Field Type Description
seats array One row per subscription

Each object in seats:

Field Type Description
product_id integer Same product_id as GET /api/v1/products/
product_name string Same product_name as the catalog
description string Same description as the catalog
charge_type string Same charge_type as the catalog: "subscription" or "on_demand"
billing_frequency string Same billing_frequency as the catalog
price_per_seat integer Same price_per_seat as the catalog
total integer Contractual seat cap (-1 = unlimited)
occupied integer Seats assigned
available integer Seats not yet assigned; -1 when total is unlimited
min_seats integer Contractual minimum seats 
{
  "seats": [
    {
      "product_id": 101,
      "product_name": "Core",
      "description": "Scan and removal subscription on the Core catalog.",
      "charge_type": "subscription",
      "billing_frequency": "monthly",
      "total": 50,
      "occupied": 12,
      "available": 38,
      "min_seats": 0,
      "price_per_seat": 999
    },
    {
      "product_id": 103,
      "product_name": "Advanced",
      "description": "Scan and removal subscription on the Advanced catalog.",
      "charge_type": "subscription",
      "billing_frequency": "monthly",
      "total": 10,
      "occupied": 2,
      "available": 8,
      "min_seats": 0,
      "price_per_seat": 1999
    }
  ]
}

Errors

Status Condition
401 Missing or invalid bearer token
403 Partner inactive

Credit pool

GET /api/v1/credits/

Unassigned on-demand credits for the partner. Assigning a credit to a member draws from available here. Buy more with POST /api/v1/credits/.

Success (200 OK)

Field Type Description
credits array One row per on-demand product

Each object in credits uses the same catalog fields as GET /api/v1/products/, plus:

Field Type Description
total integer Credits purchased
occupied integer Credits assigned to members, including credits already spent
available integer Unassigned credits. Member assignment fails when this is 0 
{
  "credits": [
    {
      "product_id": 201,
      "product_name": "Core Scan",
      "description": "On-demand scan of the Core catalog.",
      "charge_type": "on_demand",
      "billing_frequency": "one_time",
      "price_per_seat": 299,
      "total": 100,
      "occupied": 40,
      "available": 60
    }
  ]
}

Errors

Status Condition
401 Missing or invalid bearer token
403 Partner inactive