How Authentication and Category Scopes Work in Boni Supply API: A Developer Guide

What This Article Covers

The general overview explains what Boni Supply API is: a single interface that gives apps and AI agents access to real Indian commerce supply across mobility, travel experiences, accommodation, logistics, connectivity, reserved transport, and B2B trade.

This article goes one level deeper. It describes the developer model — how authentication is structured, how the scope system maps to categories, what a token-minted API call looks like in practice, and what the response contract gives you. It is written for a developer evaluating integration or preparing their first production call.

Why Indian Commerce Supply Makes Auth Harder Than a Simple API Key

Most developer platforms let you generate an API key, paste it into a header, and start calling endpoints. That works when the surface is narrow and uniform — a single provider, a single data shape, a known reliability ceiling.

Indian commerce supply is not that. Depending on which category you are calling, the supply behind the request might be an open commerce network with its own compliance and signing requirements, a direct provider integration with its own rate characteristics, a Bino-managed catalog, or some mix of all three, routed and normalized transparently. Each has different trust requirements, different failure modes, and different usage characteristics.

A naive single-key-equals-full-access model is not safe or observable enough for that substrate. The auth and scope model Boni Supply API uses is designed around this reality: an organization gets a bounded identity with explicit category permissions, and calls are validated and logged against that identity end to end.

The Four-Layer Mental Model

Before walking through the flow, it helps to hold four distinct layers in mind:

1. Organization — the legal/business entity registering for API access. One organization, one identity in the control plane.
2. Service account — a programmatic identity issued under the organization. One org can have multiple service accounts (one per service, one per environment, however you segment). Scopes are assigned at the service account level.
3. Access token — a short-lived credential minted from a service account's credentials. This is what you present on each API call.
4. Category scope — a machine-readable permission that declares what the token is allowed to do within a specific supply category.

These four layers are cleanly separate by design. You do not call a category API with a raw organizational secret. You mint a short-lived, scope-restricted token and use that. The organizational credentials stay out of each request at runtime.

Step 1: Organization Registration

A company registers with Boni Supply and creates an organization in the platform. The intake captures organization name, contact details, the categories being requested, deployment environment interest (sandbox, pre-production, or production), and intended use case.

A Boni admin reviews the signup and either approves it or requests more information. Once approved, the organization exists as a first-class tenant in the control plane with a unique identifier and an active status. The organization registry tracks approved categories, environment tiers, and any plan or rate-limit assignments.

Step 2: Service Account and Credential Issuance

Once an organization is approved, it creates one or more service accounts. Each service account is a programmatic identity — the equivalent of a user account for a machine or service rather than a human.

A service account carries:

• a unique service account identifier
• a set of allowed scopes (which categories and operations it can call)
• key material issued once at creation time (the raw secret is only retrievable at issuance; only a hashed fingerprint is stored after that)
• rotation and disable controls

The credential issued to a service account is not presented directly to category APIs at call time. It is used to mint short-lived access tokens.

Step 3: Minting a Short-Lived Access Token

The token-minting flow is the same pattern used across modern multi-tenant API platforms. Using your service account credentials, you make an authenticated call to the token endpoint (illustrative):

POST /api/auth/service-accounts/token

Authorization: Basic <base64(service_account_id:secret)>

Response:
{
  "access_token": "<signed-bearer-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scopes": ["supply.trade.search", "supply.trade.order", "supply.usage.read"]
}

The response gives you a signed, short-lived bearer token that carries the scopes assigned to the service account. You present this token on every category API call until it expires. When it expires, mint a new one.

The paths, field names, and scope strings shown throughout this article are illustrative — they explain the shape of the model, not a copy-paste API reference. The authoritative request/response contract is provided in the developer documentation you receive on registration.

Why short-lived tokens rather than persistent API keys? Several reasons:

• Reduced blast radius. A leaked token expires in minutes or hours, not weeks.
• Audit clarity. Each token has an issuance timestamp, an organization ID, and a service account ID. Usage logs can be tied to a specific minting event.
• Scope enforcement per call. The token carries the exact scope list. The execution layer validates scope presence before processing the request, without needing to hit the control plane on every call.

Step 4: Category Scopes and What They Mean

Each category is modeled as a separate permission surface. Scopes follow a structured naming pattern (illustrative: supply.<category>.<operation>). For the categories currently in scope:

Category	Search scope (illustrative)	Order scope (illustrative)
Trade and Wholesale	supply.trade.search	supply.trade.order
Logistics	supply.logistics.search	supply.logistics.order
Mobility	supply.mobility.search	supply.mobility.order
Travel Experiences	supply.travel_experiences.search	supply.travel_experiences.order
Accommodation	supply.accommodation.search	supply.accommodation.order
Reserved Transport	supply.reserved_transport.search	supply.reserved_transport.order
Connectivity (eSIM)	supply.esim.search	supply.esim.order
Usage and health	supply.usage.read	supply.health.read

An organization requesting access to trade and logistics would have a service account with scopes limited to those two categories. A mobility integration does not carry accommodation scopes and cannot call accommodation endpoints. A call presented with a token that lacks the required scope receives a clear scope-error response before any category execution happens.

This also means you can segment per service. Your backend search service gets supply.trade.search. Your order placement service gets supply.trade.search and supply.trade.order. Your monitoring tool gets supply.usage.read and supply.health.read. Each service account has the minimum scope it needs.

Step 5: Making a Category Call

With a valid token, category calls follow a consistent shape. The pattern (illustrative):

POST /categories/trade/search
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "intent": {
    "item": { "descriptor": { "name": "refined sunflower oil 15L" } },
    "fulfillment": { "type": "delivery" },
    "location": { "city": "Pune" }
  }
}

The orchestration layer validates the token and scope, then routes the request to the appropriate underlying engine. The caller does not need to know which protocol or provider is handling the query. An accommodation search sends dates and location; a logistics search sends item dimensions, pickup, and delivery addresses. The envelope shape is consistent; the intent body is category-specific.

Step 6: Parsing the Normalized Response

The response from any category search is a normalized options list, not a raw provider dump. The response shape is designed to carry enough for an AI agent or application to make a decision or present a shortlist without additional transformation.

Conceptually, each option in the response carries:

• Price and pricing model — total price, unit breakdown, inclusions, exclusions, and the pricing method (fixed, quote-required, range).
• Availability and service area — whether the option is available for the requested intent, confidence level, and any service-area limitations.
• Rank and confidence signals — why this option ranks where it does, what evidence backs it, and what level of supply readiness the option represents (raw candidate, catalog-ready, order-ready, outcome-backed).
• Next action path — how to proceed: direct order, quote request, booking confirmation, or human follow-up where automated fulfillment confidence is limited.

An AI agent consuming this response gets structured data it can reason over — not an opaque JSON blob it needs to reverse-engineer.

Step 7: Order State and Status Callbacks

The order lifecycle is part of the API contract, not an afterthought. Once you call an order endpoint and receive an acknowledgement, the platform tracks that order's state through fulfillment — acknowledged, accepted, in-progress, fulfilled, cancelled, or exception.

The organization configures webhook endpoints on the service account. When order state changes, the platform delivers a signed webhook event carrying the organization ID, order reference, new state, and category-relevant fulfillment metadata. Webhook delivery includes retry and backoff. Delivery events are logged and visible in the dashboard.

The Control Plane Dashboard

Once your integration is live, the organization dashboard gives you: enabled and pending categories, service accounts with last-active timestamps, token generation events, request volume by category broken down by success and error, per-source usage (open network, direct provider, Bino-managed), category health status, and rate limit usage relative to your plan.

This is observability at the organization level. Your organization sees its own usage, not aggregate platform traffic.

Where Maturity Stands Today

Be clear-eyed about what is running in production and what is still being built.

Control plane: the organization registry, service account model, scope assignment, and the customer-facing API dashboard have an initial implementation running. The token minting endpoint, usage ledger, and full rate-limit enforcement are in progress.

B2B Trade category: the first category where an end-to-end production flow is running. Wholesale search, supplier discovery, and order placement across B2B trade supply are the first path being validated in production.

Other categories: mobility, travel experiences, accommodation, logistics, and connectivity are in various stages of integration. Some have running execution services with significant transaction history inside Bino's consumer experience. The work being done now is connecting those execution services to the organization-scoped auth and the standard category contract shape described in this article.

The platform is being built to a multi-tenant standard from the start — not a collection of one-off endpoints that gets retrofitted later. The scope names, response shapes, and control plane design are set with the full category set in mind, even while individual categories are wired in sequence.

If you are evaluating whether to build on Boni Supply API now or wait: registering now, getting access to the categories closest to your use case, and integrating iteratively is the better path. Feedback from early integrations directly shapes how category contracts get finalized.

Who Should Request Access

AI application builders whose agents need to move from recommending to actually transacting in India. The scope model and token shape are designed for machine consumption — an agent runtime or tool-calling framework can call Boni Supply categories with standard HTTP patterns.

B2B procurement and distribution workflows where the trade category's supplier search and order placement can replace manual processes.

Logistics, travel, and hospitality apps that need category supply without building separate integrations for each provider or network.

Enterprise platforms adding commerce — MSME tools, finance apps, or sector-specific SaaS products that need structured supply access without vertical integration work.

If you are building an application or agent that needs real transactional access to Indian commerce supply, Boni Supply API is where to request access and start integrating.