Bootstrap an embed token

0Gate is the primary public integration path for hosted payment, ramp, and swap experiences. Keep secret-key operations on your server and hand only browser-safe values to the widget.

Bootstrap is the one and only call the browser makes with a publishable key. It exchanges the pk_* (plus an optional session clientSecret) for a short-lived embed token (a JWT) that the iframe then sends as X-Embed-Token on every subsequent request. Everything else in 0Gate runs server-side with your secret key.

Endpoint

Use it for

Exchange a publishable key and optional client secret for a short-lived embed token.

Use this endpoint only for the partner-scoped resource it describes. Store your own reference id, the returned 0Bit object id, the request id, timestamps, and the current status so support and reconciliation do not depend on browser callbacks alone.

Authentication

This is the only public endpoint authenticated with a publishable key (pk_test_* / pk_live_*). Publishable keys are browser-safe and may only call bootstrap; every other 0Gate endpoint requires a secret key (sk_*) and must run on your server.

The publishable key is accepted from any of three locations, checked in this order:

The request Origin (or Referer fallback) must be an exact match for one of your configured allowed domains — no wildcards. A browser caller with no Origin/Referer is refused.

Production rules

• Keep secret keys on your server. Bootstrap uses the publishable key only.
• Register every embedding origin in your allowed domains before going live — an unlisted origin is rejected.
• Pass the session clientSecret whenever you create a session server-side, so the embed token is bound to that session's locked amount and currency.
• Branch on machine-readable status, error code, object id, and request id.
• Treat examples and placeholder ids as fake data only.

Request body

The body is optional. A bare bootstrap (no body) mints a session-less token for partners not yet using sessions.

An invalid, expired, already-consumed, or cross-partner/cross-mode clientSecret is rejected with 403.

Response

The response is HTTP 200 with the embed token and the context the iframe needs to render. When the call is session-bound, the locked session details are echoed back so the iframe can show the right amount and flow.

Examples

curl -X POST https://gate-api.0bit.app/v1/embed/bootstrap \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Origin: https://app.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "gsec_test_67a1f3b9000000000000_AbCdEfPlaceholder0123456789"
  }'

{
  "embed_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC9.test.placeholder",
  "expires_at": "2026-01-01T01:00:00Z",
  "partner_id": "ptnr_test_000000000123",
  "mode": "test",
  "session_id": "gs_test_000000000456",
  "amount": "100.00",
  "currency": "EUR",
  "target_token": "USDT",
  "target_network": "arbitrum",
  "return_url": "https://app.example.com/checkout/return",
  "flow": "on_ramp",
  "available": true,
  "unavailable_reason": null,
  "frame_ancestors_policy": "frame-ancestors https://app.example.com",
  "theme": null
}

{
  "embed_token": "",
  "expires_at": "2026-01-01T00:01:00Z",
  "partner_id": "ptnr_test_000000000123",
  "mode": "live",
  "session_id": null,
  "amount": null,
  "currency": null,
  "target_token": null,
  "target_network": null,
  "return_url": null,
  "flow": null,
  "available": false,
  "unavailable_reason": "quota_exceeded",
  "frame_ancestors_policy": "frame-ancestors https://app.example.com",
  "theme": null
}

Errors

All errors use the unified envelope and carry an X-Request-Id response header. Branch on code/type/statusCode, not on the free-form message.

{
  "type": "forbidden",
  "code": "forbidden",
  "message": "Example credential error using fake data.",
  "request_id": "req_test_000000000123",
  "doc_url": null,
  "statusCode": 403
}

Public boundary

This reference covers partner-scoped endpoint behavior, authentication, idempotency, webhook verification, and support-safe records. Internal operations, administrative routes, and unsupported availability claims are outside the public API contract.

Related pages