Developer integration guide

Connect your portal, agents, processors, and authorization APIs to Auctra.

This guide explains how developers integrate with Auctra from account setup through real-time authorization decisions.

Open portalAPI reference

Integration surface

Portal plus API workflow

Portal

Accounts, teams, credentials, sandbox, production access

Enterprise APIs

Agents, spending authorities, policies, bindings, intents

Processor APIs

Real-time authorization decisions

Dashboards

Metrics, authorizations, audit trail, billing

Start here

Integration checklist

Use this sequence when connecting a new enterprise, processor, or integration environment.

1

Create your portal account

Sign up, verify your email, and create either an Enterprise account or a Processor account from the dashboard.

2

Create API credentials

Open Settings > API Credentials and generate an API key plus shared secret. Store the secret in your backend only.

3

Model your spend controls

Enterprises create agents, spending authorities, policies, and bindings before sending live authorization traffic.

4

Call the authorization APIs

Enterprises can validate an agent intent before the agent acts. Processors call the real-time authorization endpoint when a payment event arrives.

5

Move from sandbox to production

Test in sandbox first, then request Go-Live access from the portal. Auctra admins approve production access before live use.

Core model

Objects developers need to understand

Auctra separates who owns the spend, who initiates it, what credential is used, and which policy decides the outcome.

Enterprise

The company or platform that owns agents and defines spend controls.

Processor

The issuer, issuer processor, or payment infrastructure provider calling Auctra at authorization time.

Agent

An AI agent, workflow, service account, or automated buyer that may initiate spend.

Spending Authority

The spend-control container attached to an agent. It holds mode, status, policy, and bindings.

Policy

A template-backed rule set such as max amount, merchant lock, MCC allowlist, or human review.

Binding

The link between a payment credential, token, card, account, or instrument and a spending authority.

Intent

A preliminary validation record for an agent’s planned spend, used to check limits and policy eligibility before the agent proceeds.

Observe / Enforce

Observe approves but records what would have happened. Enforce applies the decision.

Portal setup

How teams connect through the Auctra portal

The portal is where teams create accounts, manage credentials, configure controls, review decisions, and request production access.

Enterprise portal

Enterprise users manage agents, spending authorities, bindings, policies, authorizations, activity logs, team members, and API credentials.

Open enterprise dashboard

Processor portal

Processor users review authorization traffic, inspect performance, manage credentials, and debug real-time decision requests.

Open processor dashboard

Production access

New organizations start in sandbox. Owners can request Go-Live access from the dashboard, then switch between sandbox and production after approval.

Request access

Authentication

API requests use signed JWT bearer tokens

Create a short-lived JWT in your backend. The token's key_id must be your raw Auctra API key, and the token must be signed with your shared secret using HS256.

Get credentials

Generate API credentials from Settings > API Credentials in the portal.

Sign server-side

Never sign tokens in the browser or mobile app. Keep the shared secret in a backend secret manager.

Use bearer auth

Send Authorization: Bearer <token> on each API request.

Separate roles

Use enterprise credentials for setup and intent APIs. Use processor credentials for /v1/authorize.

import jwt from 'jsonwebtoken'

const apiKey = process.env.AUCTRA_API_KEY
const sharedSecret = process.env.AUCTRA_SHARED_SECRET

const now = Math.floor(Date.now() / 1000)

const token = jwt.sign(
  {
    key_id: apiKey,
    iat: now,
    exp: now + 3600,
  },
  sharedSecret,
  { algorithm: 'HS256' }
)

const headers = {
  Authorization: `Bearer ${token}`,
  'Content-Type': 'application/json',
}

Integration paths

Enterprise and processor responsibilities

Most integrations have two sides: the enterprise side defines permissions, and the processor side asks Auctra for the live decision.

Enterprise integration

  1. Create or select your enterprise in the portal.
  2. Create one agent per automated actor or spending workflow.
  3. Create a spending authority for each permission boundary.
  4. Choose a policy template and configure parameters.
  5. Create one or more bindings for the card, token, account, or payment credential.
  6. Optionally call /v1/authorize-intent before the agent proceeds, so the enterprise can validate limits, policy fit, and purchase eligibility.

Processor integration

  1. Create or select your processor account in the portal.
  2. Generate processor API credentials with authorization scope.
  3. When a network authorization or payment event arrives, map it to a binding_id, instrument_id, or intent_reference.
  4. Call /v1/authorize with amount, currency, MCC, merchant, issuing platform, and lookup reference.
  5. Use APPROVE or DECLINE from the response in your payment authorization path.
  6. Send request IDs and correlation IDs to support when debugging production traffic.

API surface

Core endpoints

These are the primary endpoints most integrations use. The API reference contains the full list of management, dashboard, admin, and audit endpoints.

Method
Endpoint
GET
/v1/policy-templates

Public

List available policy templates and their parameter schemas.

POST
/v1/enterprises/{enterprise_id}/agents

Enterprise JWT

Create an agent controlled by the enterprise.

POST
/v1/spending-authorities

Enterprise JWT

Create a spending authority with a template-backed policy.

POST
/v1/bindings

Enterprise JWT

Attach a payment credential or instrument to a spending authority.

POST
/v1/authorize-intent

Enterprise JWT

Run enterprise-side preliminary validation for an agent’s planned spend.

POST
/v1/authorize

Processor JWT

Return the real-time authorization decision for a payment event.

View complete API reference

Authorization flows

Pre-authorization validation and real-time decisions

Use intent authorization when an enterprise wants to run preliminary checks before an agent attempts a purchase. This verifies whether the agent is allowed to proceed, whether limits remain available, and whether the planned spend qualifies under policy.

Validate an agent intent

Called by the enterprise before the agent acts. Auctra evaluates the requested amount, merchant, MCC, and spending authority policy so the enterprise can decide whether the agent should continue.

curl -X POST https://api.auctra.io/v1/authorize-intent \
  -H "Authorization: Bearer $AUCTRA_ENTERPRISE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "spending_authority_id": "sa_123",
    "amount": 4999,
    "currency": "USD",
    "mcc": "5734",
    "merchant": "Software Store",
    "intent_ttl_seconds": 86400
  }'

Authorize the payment

Called by the processor when the payment authorization arrives. The response contains the final decision and reason code.

curl -X POST https://api.auctra.io/v1/authorize \
  -H "Authorization: Bearer $AUCTRA_PROCESSOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_reference": "intent_abc123",
    "binding_id": "bind_123",
    "issuing_platform": "MARQETA",
    "amount": 4999,
    "currency": "USD",
    "mcc": "5734",
    "merchant": "Software Store"
  }'

Decisions

Handling responses and reason codes

Authorization responses are designed to be simple enough for real-time payment paths and detailed enough for debugging.

Decision contract

Treat decision as the payment action. Store request_id, policy_id, binding_id, intent_reference, and reason_code for reconciliation and support.

POLICY_MATCH

The transaction matched active policy constraints.

POLICY_VIOLATION_AMOUNT

The amount exceeded the configured threshold.

POLICY_VIOLATION_MCC

The MCC did not satisfy the policy.

POLICY_VIOLATION_MERCHANT

The merchant did not satisfy the policy.

OBSERVE_ONLY

The policy would have been evaluated, but the authority is in observe mode.

NO_POLICY

No active policy was found for the referenced authority or binding.

Operational guidance

Production readiness checklist

Before sending live traffic, make sure your team has the right safeguards, logging, and environment separation.

Keep shared secrets in server-side secret storage.

Use short JWT expirations and regenerate tokens automatically.

Test observe mode before switching authorities to enforce mode.

Store Auctra request IDs and correlation IDs in your logs.

Design a clear fallback policy for network errors.

Request production access only after sandbox traffic is validated.