Authenticate & make your first call

The Reseller API is a partner-facing surface under /external/*. A reseller is an institution that owns and manages a set of child institutions (the banks and credit unions you serve). You authenticate once with a service account, then act on behalf of any child institution you own.

Key concepts

• Service account — an email/password credential tied to your reseller institution. It is the root of trust for everything else.
• SSO token — a short-lived Guid you receive after a service-account login. You send it on every subsequent call. Tokens expire after 30 minutes, and the window slides forward 30 minutes on each successful request.
• Institution key — the unique key identifying a child institution. You name the institution you're acting on via the InstitutionKey header.
• Requested-by — the core username of the operator performing the action, sent via the RequestedBy header. It is recorded on the resulting activity for audit.

The three authentication modes

Each endpoint uses one of three patterns. The reference lists the mode per endpoint.

Step-by-step: acquiring tokens

1. Log in with your service account

   POST /external/token/request — send your onboarding accessToken header and your service-account credentials in the body. You receive an SsoToken plus the list of institution keys you can manage.

   Request

   curl -X POST https://api.getconfirmed.org/external/token/request \
     -H "accessToken: <your-onboarding-access-token>" \
     -H "Content-Type: application/json" \
     -d '{
           "email": "svc@your-reseller.com",
           "password": "••••••••"
         }'

   Response 200

   {
     "success": true,
     "token": "8f1c0e2a-7b34-4a5d-9c2e-1f6b9a0d4e77",
     "expiresOn": "2026-06-14T22:30:00+00:00",
     "institutionKeys": ["acme-cu", "first-state-bank"]
   }

2. Use the SSO token on every call

   For institution-management endpoints, the SsoToken header alone is enough. For call/voice endpoints, also name the child institution and operator:

   Headers (service-account endpoints)

   SsoToken: 8f1c0e2a-7b34-4a5d-9c2e-1f6b9a0d4e77
   InstitutionKey: acme-cu
   RequestedBy: jdoe

3. (Optional) Exchange for a per-institution user token

   POST /external/token/request/user — with the service-account headers above, mint a temporary 30-minute login token for a specific child institution (used to drop an operator straight into that institution's dashboard).

   Request & response

   curl -X POST https://api.getconfirmed.org/external/token/request/user \
     -H "SsoToken: 8f1c0e2a-7b34-4a5d-9c2e-1f6b9a0d4e77" \
     -H "InstitutionKey: acme-cu" \
     -H "RequestedBy: jdoe"
   
   → { "success": true, "token": "2b9d…f0a1" }

A complete worked example

Once you hold an SsoToken, pull the verification queue for one of your institutions:

const base = "https://api.getconfirmed.org";

// 1. Service-account login
const login = await fetch(`${base}/external/token/request`, {
  method: "POST",
  headers: { "accessToken": ACCESS_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({ email: SVC_EMAIL, password: SVC_PASSWORD }),
}).then(r => r.json());

// 2. Work the queue for one institution
const queue = await fetch(`${base}/external/calls/queue`, {
  headers: {
    "SsoToken": login.token,
    "InstitutionKey": "acme-cu",
    "RequestedBy": "jdoe",
  },
}).then(r => r.json());

console.log(queue.phoneCalls);

Response shape

Every endpoint returns a JSON object with a success boolean and, on failure, an error message — alongside any endpoint-specific data. Always branch on success rather than the HTTP status alone.

{ "success": false, "error": "Phone call not found" }

Open the API reference →