Worked example · partner integration

Add a “Get your tax report” button to SixpenceX

This is the live, openly-readable walkthrough of the Coinfig partner integration. SixpenceX is a fictional exchange we use as the worked example so prospective partners can validate the whole flow — read the API, walk the handoff, send a sandbox request — before committing a single sprint.

▶ Jump to the sandbox·← Back to the partner programme

How it works

SixpenceX adds a “Get your tax report” entry point — a button in the portfolio screen, a profile-menu row, or a tax-season banner. When a user opts in:

1. User opts in inside SixpenceXThey tap “Get your tax report” and consent to share read-only history with Coinfig.
2. SixpenceX's backend mints a read-only API keyGenerate (or reuse) a per-user API key/secret with read-only permissions scoped to transaction history.
3. SixpenceX calls one Coinfig endpointA single POST with the user's email and those credentials, authenticated with SixpenceX's partner bearer token.
4. Coinfig provisions the accountWe create or find the user, attach the SixpenceX data source, and begin importing transactions.
5. Coinfig returns a passwordless sign-in linkA time-limited redirect_url comes back in the response.
6. SixpenceX redirects the userThey land in Coinfig already signed in — no password needed on first arrival — with their history syncing in the background.

Authentication

Coinfig issues each real partner a unique bearer token per environment. It is stored only as a SHA-256 hash on the Coinfig side and can be rotated on request. Keep it in the partner's server-side secret store.

Authorization: Bearer <PARTNER_TOKEN>

Endpoint

# Provisions (or finds) a Coinfig user, attaches the SixpenceX source,
# starts the import, and returns a passwordless sign-in link.
POST https://api.coinfig.tax/api/v1/partner/register
Authorization: Bearer <PARTNER_TOKEN>
Content-Type: application/json

Request

Send a JSON body. Content-Type must be application/json.

{
  "email": "user@example.com",
  "name": "Jordan",
  "surname": "Mensah",
  "partner_source": "SIXPENCE",
  "discount_code": "SIXPENCE_WELCOME_500",
  "jurisdiction": "RSA",
  "api_credentials": [
    {
      "exchange_name": "SIXPENCE",
      "api_key": "user_sixpencex_api_key",
      "api_secret": "user_sixpencex_api_secret"
    }
  ]
}

Fields

Response

A new user returns 201 Created. An existing user returns 200 OK with the same shape and user_created: false. Sources already present return status: "skipped_duplicate".

{
  "user_id": "usr_01HZA9F3K2WPS6T4VYXNK8B0Q1",
  "user_created": true,
  "sources_added": 1,
  "sources": [
    {
      "source_id": "src_01HZA9F3K2WPS6T4VYXNK8B0Q2",
      "exchange_name": "SIXPENCE",
      "status": "processing"
    }
  ],
  "discount_applied": true,
  "discount_code": "SIXPENCE_WELCOME_500",
  "redirect_url": "https://coinfig.tax/r/eyJhbGciOi…",
  "redirect_expires_at": "2026-07-23T08:15:00Z"
}

Fields SixpenceX should use

The redirect handoff

The redirect_url is the entire handoff. You don't need to embed Coinfig or share session state — just redirect the user's browser to that URL. The link carries a signed, single-use sign-in token; Coinfig validates it and drops the user into their report area.

• Single use. Once consumed, the URL is invalid. Generate a fresh one if you need to re-link.
• Time-limited. Default lifetime is 30 days, but you should redirect immediately on the same request.
• Stateful only at Coinfig. SixpenceX doesn't store the URL — it's user-facing once and then discarded.

# pseudo-code, any language
resp = post("https://api.coinfig.tax/api/v1/partner/register", ...)
redirect(resp.body.redirect_url, status=302)

Errors

Try the sandbox

Edit the payload and hit Send request. The browser POSTs to this site's same-origin proxy, which adds the SixpenceX bearer token server-side and forwards the call to Coinfig's real partner API. The bearer never reaches the browser. The request body is exactly what a real SixpenceX backend would send.

Integration checklist

1. Apply via the partner programme and receive your bearer token (staging first) from Coinfig.
2. Store the token in the partner's server-side secret manager.
3. Add a “Get your tax report” entry point in the partner UI.
4. On opt-in, generate a read-only API key for that user (or reuse an existing one).
5. Call POST /api/v1/partner/register from the partner's backend with the payload above.
6. Redirect the user to the returned redirect_url.
7. Test against staging end-to-end, then repeat on production with the production token.

Testing on staging

1. Get your staging bearer from Coinfig.
2. Send the curl below against staging.
3. Expect 201, sources_added: 1, and a redirect_url.
4. Open redirect_url in a browser — you should land in Coinfig signed in.
5. Wait ~1–2 minutes; the source moves from processing to populated.

curl -sS -X POST https://staging-api.coinfig.tax/api/v1/partner/register \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-test+sixpencex@example.com",
    "partner_source": "SIXPENCE",
    "jurisdiction": "RSA",
    "api_credentials": [
      { "exchange_name": "SIXPENCE", "api_key": "<read_only_key>",
        "api_secret": "<read_only_secret>" }
    ]
  }'

Security

• Server-to-server only — the bearer token never leaves the partner's backend.
• Exchange API keys should be read-only; Coinfig never trades or withdraws.
• Credentials are encrypted at rest (AES-256), decrypted only during sync.
• Sign-in links are cryptographically signed and single-use.
• All data access is scoped per user.

Browser ──▶ Partner backend ──▶ Coinfig Partner API ──▶ returns redirect_url ──▶ user lands signed in
            (holds the bearer token)

OAuth 2.0 Planned · not yet available

For partners that prefer not to handle exchange API credentials, we are scoping an OAuth-style flow where the user authorises Coinfig directly with the partner — no bearer-mediated key handoff. The partner-facing API stays the same shape; only the credential exchange changes. We'll publish dates as we close out the pilot.

Talk to us

Convinced? Apply to partner via the partner programme application form. The Coinfig team reviews, sends your private docs and bearer, and a real human is on the other end if you get stuck.