Integrator Registration

Registration Endpoint

cURL

curl -X POST https://api.ixblix.app/api/integrators/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My CRM Platform",
    "hostname": "mycrm.example.com",
    "callbackUrl": "https://mycrm.example.com/ixblix/callback"
  }'

Request Fields

Field	Required	Description
`name`	Yes	Display name of your integrator.
`hostname`	Yes	Unique hostname for this integrator. Must be unique across all integrators.
`callbackUrl`	Yes	URL where ixblix sends credentials for verification.
`force`	No	If true, allows replacing an existing verified hostname registration. Defaults to false.
`subscriptionId`	No	Subscription identifier in the format `{paymentProvider}:{id}`. The `id` portion is opaque to the API and interpreted by the payment provider internally. Required when the assigned payment provider needs a subscription reference.

 Callback Verification Flow
 Registration happens in three phases:
  You call POST /api/integrators/register with your details.
 ixblix sends a challenge to your callbackUrl:
  Challenge payload  
 {
  "challenge": "mycrm.example.com"
}
  
Your endpoint must respond with 200 OK and the exact registration payload you sent in phase 1.
 ixblix sends your credentials to the same callbackUrl:
  Credentials payload  
 {
  "event": "INTEGRATOR_CREDENTIALS",
  "integratorId": "int_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accessToken": "ixblix_integrator_token_xxxxxxxxxxxx",
  "timestamp": "2026-01-15T10:30:00.000Z"
}
  
Your endpoint must echo the credentials payload back with 200 OK.
 
 Store the credentials securely — they are used for all subsequent API calls.
 Using Credentials
 Use integrator credentials as HTTP Basic Auth:
   cURL  
 curl https://api.ixblix.app/api/plans \
  -u "int_a1b2c3d4-...:ixblix_integrator_token_xxxx"
 
  Callback Handler Example
   Express handler  
 import express from 'express';
const app = express();
app.use(express.json());

// The registration payload you sent in phase 1
const registrationPayload = {
  name: "My CRM Platform",
  hostname: "mycrm.example.com",
  callbackUrl: "https://mycrm.example.com/ixblix/callback",
};

app.post('/ixblix/callback', async (req, res) => {
  // Phase 2: answer the challenge with the original registration payload
  if (req.body?.challenge) {
    return res.status(200).json(registrationPayload);
  }

  // Phase 3: store credentials and echo them back
  if (req.body?.event === "INTEGRATOR_CREDENTIALS") {
    const { integratorId, accessToken } = req.body;
    await saveIntegratorCredentials({ integratorId, accessToken });
    return res.status(200).json(req.body);
  }

  res.status(200).json({ received: true });
});
 
    ← Previous Quick Start   Next → Company Registration