# 1. Init Onboard Session

Start onboarding for a store integration at Toco.

This endpoint creates a short-lived onboard session token that expires 3 minutes after it is issued.
If the seller does not start the flow within this window, the partner must create a new session.

Overview

HMAC

Auth: HMAC Partner
Method: POST

# Path

https://partners-api.tocobagus.net/api/v1 /partner/onboard/sessions

# Request

Query parameters: None.

# Required Headers

Header	Example	Description
`x-signature`	bdbb8833fe43671e058b56dace75763a78a2edf8de7365afb6f534d750056e80	HMAC signature of the request, computed with the partner secret and `x-timestamp` (auth integrity).
`x-partner-client-id`	2025112012475048491498	Partner identifier issued by Omni; used to locate the partner secret.
`x-timestamp`	1758100350458	UNIX epoch timestamp used when computing `x-signature` (replay protection).

# Request Payload

Content-Type: application/json

# Example Body Payload

{
  "redirectUri": "https://bigseller.com/login/email-login?redirect=/shopset/toco"
}

# Example Request

Curl Node.js Go Java

curl -X POST "http:///partner/onboard/sessions" \
  -H "Content-Type: application/json" \
  -H "x-signature: bdbb8833fe43671e058b56dace75763a78a2edf8de7365afb6f534d750056e80" \
  -H "x-partner-client-id: 2025112012475048491498" \
  -H "x-timestamp: 1758100350458" \
  --data '{"redirectUri":"https://bigseller.com/login/email-login?redirect=/shopset/toco"}'

const qs = new URLSearchParams({});
const url = "http:///partner/onboard/sessions" + (qs.toString() ? "?" + qs.toString() : "");
const res = await fetch(url, {
  method: "POST",
  headers: {
  "x-signature": "bdbb8833fe43671e058b56dace75763a78a2edf8de7365afb6f534d750056e80",
  "x-partner-client-id": "2025112012475048491498",
  "x-timestamp": "1758100350458"
},
  body: JSON.stringify({"redirectUri":"https://bigseller.com/login/email-login?redirect=/shopset/toco"})
});
const json = await res.json();
console.log(json);

qs := url.Values{}

u := "http:///partner/onboard/sessions"
if q := qs.Encode(); q != "" { u = u + "?" + q }
req, _ := http.NewRequest("POST", u, bytes.NewBufferString("{\"redirectUri\":\"https://bigseller.com/login/email-login?redirect=/shopset/toco\"}"))
req.Header.Set("x-signature", "bdbb8833fe43671e058b56dace75763a78a2edf8de7365afb6f534d750056e80")
req.Header.Set("x-partner-client-id", "2025112012475048491498")
req.Header.Set("x-timestamp", "1758100350458")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))

var client = java.net.http.HttpClient.newHttpClient();
var req = java.net.http.HttpRequest.newBuilder()
    .uri(java.net.URI.create("http:///partner/onboard/sessions"))
    .header("Content-Type","application/json")
    .header("x-signature", "bdbb8833fe43671e058b56dace75763a78a2edf8de7365afb6f534d750056e80")
    .header("x-partner-client-id", "2025112012475048491498")
    .header("x-timestamp", "1758100350458")
    .method("POST", java.net.http.HttpRequest.BodyPublishers.ofString("{\"redirectUri\":\"https://bigseller.com/login/email-login?redirect=/shopset/toco\"}"))
    .build();
var res = client.send(req, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

# Responses

# Example Responses

201 Created

{
  "onboardUrl": "https://seller-staging.tocobagus.com/auth/partner?clientId=ptnr_1s4UqMnO64&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJvbW5pLWF1dGgiLCJhdWQiOiJvbW5pLW9uYm9hcmQiLCJzaWQiOiIxZmVjZTI5ZS1mOWI0LTQ4NDItYWIzNC1lYjFmNjg5OWU1MjkiLCJwaWQiOiI0Y2MxNWIxOC1mZGJhLTRkMTctOTBmMy0xZWZiMDc1YjFmYWEiLCJyZWRpcmVjdFVyaSI6Imh0dHBzOi8vYWRtaW4uZGVzdHkub25lL2xvZ2luL2VtYWlsLWxvZ2luP3JlZGlyZWN0PS9zaG9wc2V0L3RvY28iLCJqdGkiOiI5YWUxZTk0ZS0zNGJhLTQ5YjctOGU3ZC04M2I2M2E2ZjQ3MDkiLCJpYXQiOjE3NjM2NDkyMjIsImV4cCI6MTc2MzY0OTUyMn0.qYH63zl9SsQTsojwRprst7PonB4ajzTVHPSBYrGAKrE&requestId=4b0007c7-d471-445d-909a-35e58ded2c95",
  "sid": "1fece29e-f9b4-4842-ab34-eb1f6899e529",
  "requestId": "4b0007c7-d471-445d-909a-35e58ded2c95"
}

400 Bad Request

{
  "success": false,
  "error": {
    "code": "AUTH_003",
    "message": "Expired or invalid timestamp",
    "details": {
      "timestamp": "2025-08-29T09:36:23.490Z",
      "hint": "Request timestamp must be within 300 seconds",
      "context": {
        "providedTimestamp": 1756459527238,
        "currentTime": 1756460183490,
        "ageSeconds": 656
      }
    }
  },
  "requestId": "b1df066d-d925-4174-9514-40aa69b6c527"
}

# Dictionary

None for this endpoint.

# Notes

onboardUrl embeds a short-lived onboard session token.
The onboard session token expires 3 minutes after this API is called.
If the seller opens an expired onboardUrl, the onboarding page rejects the request and the partner must create a new onboard session.