The channel API for resellers

The channel API lets a partner app sell domains to its own customers and point them, without those customers signing in to Taji.

Who it is for

It is for partner apps, such as a website builder, that sell domains under their own name. Taji gives each partner a code, such as buninow, and a consumer key with one or both scopes:

• CHANNEL_DOMAINS: search, customers, register and order status.
• CHANNEL_DNS: DNS changes and grants on domains you sold or were given.

A host’s own API key does not work here, and a consumer key does not work on /v1/api/*.

The basics

• Base address: https://YOUR_API_ADDRESS, the platform API address Taji gives you with your key. The contract lists api.sandbox.hackflix.net for sandbox tests.
• Send Authorization: Bearer YOUR_CONSUMER_KEY on every call, server to server.
• Every body carries onBehalfOf.consumer, your code. It must match your key, or the answer is 403 CONSUMER_MISMATCH.
• onBehalfOf.customerRef is your own reference for your customer, such as bn_usr_7f3a2c.
• Every POST that changes something needs an Idempotency-Key. See Idempotency and retries.

1. Search for a name

curl -X POST https://YOUR_API_ADDRESS/v1/channel/domains/search \
  -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sld":"umusozi-crafts","tlds":["rw","com"],"currency":"RWF","onBehalfOf":{"consumer":"YOUR_CODE"}}'

Each result has a status: AVAILABLE, TAKEN, UNKNOWN, RESERVED or NOT_SOLD. Only an AVAILABLE name has a price, your price for one year. UNKNOWN means the registry has not answered yet.

2. Say who the customer is

Before you register anything, make the customer with PUT /v1/channel/customers/{customerRef}. Send kind (BUSINESS or INDIVIDUAL), name and countryCode, and the TIN if you have it. The first call answers 201; later calls update the same customer and answer 200.

If your user already has an account with the host, link it instead:

1. POST /v1/channel/customers/{customerRef}/link with their email or phone, and the domains you would like to manage. It always answers 202 with a linkId, whether or not anyone matched.
2. Your user gets a six-digit code on their own phone or email and types it into your screen.
3. POST /v1/channel/links/{linkId}/confirm with the code. The customer is linked and you get the domains they hold.

A code works for 10 minutes and survives 5 wrong tries.

3. Register a domain

Call this only after your customer has paid you. Taji never takes money from them.

curl -X POST https://YOUR_API_ADDRESS/v1/channel/domains/register \
  -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  -H "Idempotency-Key: YOUR_ORDER_REFERENCE" \
  -H "Content-Type: application/json" \
  -d @register.json

The body holds domain, years, price, registrant and onBehalfOf with customerRef. price must be exactly your price in force times years, as an object such as {"amountMinor": 12000, "currency": "RWF"}. If it is not, the answer is 409 PRICE_CHANGED and nothing is written.

The Idempotency-Key is your own order reference. The same reference twice is one order.

The answer is 202 with an orderId and status PENDING. The result comes as a domain.registered or domain.failed webhook. You can also read it at GET /v1/channel/domains/{orderId}.

Endings that need a registrant document, such as .rw, are refused with 400 DOCUMENT_REQUIRED for now.

4. Point the domain

curl -X POST https://YOUR_API_ADDRESS/v1/channel/dns/records \
  -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  -H "Idempotency-Key: YOUR_CHANGE_REFERENCE" \
  -H "Content-Type: application/json" \
  -d '{"domain":"umusozi-crafts.com","records":[{"type":"ALIAS","host":"@","value":"sites.example.com"}],"onBehalfOf":{"consumer":"YOUR_CODE","customerRef":"YOUR_CUSTOMER_REF"}}'

For each type and host you send, the records become exactly the ones sent. Other records stay as they are. ALIAS points the bare domain at a hostname, and works only while the domain uses Taji’s nameservers. The answer is 202, and a dns.updated webhook says APPLIED or FAILED. You can also read GET /v1/channel/dns/changes/{changeId}.

You can change DNS only on a domain you hold a live grant for. You get one when you sell it, or when the customer links or allows you. The customer can turn it off in their client area.

Grants

• GET /v1/channel/customers/{customerRef}/grants lists the domains you may manage for that customer.
• DELETE /v1/channel/customers/{customerRef}/grants/{domain} gives one up.
• grant.created and grant.revoked webhooks tell you when this changes without you.

Channel webhooks are signed and retried the same way as a host’s. See Webhooks and signatures.

Limits

Each partner may make a set number of requests a minute across all its keys. Past that the answer is 429 RATE_LIMITED with Retry-After.

If something goes wrong

Contact Taji support at [email protected] or +250782009639.