# 1. Onboard

Onboard — Partner Store Integration

Connect a partner’s store to Toco through a secure, OAuth-like flow that issues the store credentials used by all partner APIs.

• Init Onboard Session (backend-to-backend)
  The Omnichannel Platform calls POST /partner/onboard/sessions with a redirectUri (HTTPS URL on the partner side).
  Toco creates an onboarding session and returns a seller-specific onboardUrl.

  Credentials are never returned in this response.

• Credential issuance (after seller consent)
  Once the seller logs in on Toco and completes the authorization screens, Toco:

  • Creates (or links) the store in Toco.
  • Generates the store access credential (for example clientId and store token).
  • Encrypts the credential using the partner’s configured encryption_key.

• Credential delivery modes

  • If the partner has a webhook registered:
    • Toco sends the encrypted store credentials to the partner’s webhook, and
    • Redirects the seller back to the partner redirectUri, including store information and the encrypted credential in the query string.
  • If the partner does not have a webhook:
    • Toco only redirects the seller back to the partner redirectUri with the store information and encrypted credential in the query string.

• Store + credential lifecycle

  • The onboarding + grant-access flow is effectively one-time per active store — the same Toco store cannot be registered again while its store record is still active.
  • To obtain a new credential for the same store (re-consent / rotation), the store must first be unbound via the Toco Seller Dashboard or the partner dashboard; only then can the onboarding flow be run again.
  • The partner redirectUri must:
    • Be a valid HTTPS URL owned by the partner, and
    • Handle sid and storeAccess query parameters and persist the decrypted credentials on the partner’s backend.

If you send the following in POST /partner/onboard/sessions:

{
  "redirectUri": "https://admin.desty.one/login/email-login?redirect=/shopset/toco"
}

After the seller completes onboarding and access is granted, Toco will redirect the seller to a URL like:

https://admin.desty.one/login/email-login?redirect=/shopset/toco&sid=b7691d02-ed51-4ff0-990f-a1ef4217a2e5&storeAccess=ENCRYPTED:gsCMXIrp4CIU4+WnMyErUEdwjNOisUJYJPgiPbREEnAMor9OQr0rQLs8COt92mDT9NE0lHrfsIe0y5M6EZTMkwEU6xtXfwDNYk1yodwV5tcSyTK8wFowMJ1reptwNCqSdgirLVwN+Ga8rStnpBaN69UhXhBpI6+eD4LEljt6zSupoQn6tz1pGSxKn082HgRZJeOb8Ts9M1xXWIDwMNwW8pbJ3XY+Gz3LCROZx2z4gdDSYPdUAaorh5w67T34gZWuTRdArw8G0cTvKAUzukEW9xq/B6+O0uIz1YeQtpZLjSXqQIaKNtAMSNSUiB5+uVLQA/R73pZoVCEprSi7a4fB+kfsDsNzPJRAgC4Yp+dgjhcpI8CFVR9sTO3q79xgkKXwdfvEqOyNP1kvVIlU8qkxW0JKqV4EWEGgatcyLPw2tHuWrLYYAkstDt1ViB/2Z5nUzYLNfeOaInZbAILVZksxoTe5jTcLYJ48bWOjIGKASzy3v8NTnWRHKPFkpzxMTR7Hbwc=

Where:

• sid is the onboarding session identifier.

• storeAccess is the URL-encoded encrypted store credential, starting with the ENCRYPTED: prefix before URL encoding.

Example of decrypted storeAccess
After you URL-decode storeAccess and decrypt it using your configured encryption_key, you can expect a JSON payload similar to:

{
  "clientId": "str_bG7SUfKOqSQt",
  "name": "lopiop43099fdkj",
  "avatarUrl": "https://toco-img.azureedge.net/toco/665d6e1a-ad25-452b-9819-e078087108ae-9c4b49e1-6afe-4296-a3fa-d176fc68f28a-hl_image_picker_20250530014414473.jpg",
  "storeUrl": "https://web-staging.tocobagus.net/store/lopiop43099fdkj",
  "token": "stkn_xNeNeuqg0XlrzHAh",
  "expiresAt": "2026-01-12T00:00:00.000Z"
}

Notes

• The onboarding + grant-access flow is effectively one-time per store:
  the same Toco store cannot be registered again while its store record is still active.

• To obtain a new store credential for the same store (e.g. “re-consent” / rotation), the store must first be unbound the authorization from Toco via the Toco seller dashboard or Partner dashboard. Only then can the onboarding flow be run again successfully.

• The redirectUri must:

  • Be a valid HTTPS URL owned by the partner, and

  • Handle the sid and storeAccess query parameters and persist the decrypted credentials on the partner’s backend.

meta
{
  "diagram": "static/flows/1-onboard/sequence.png",
  "explanation": [
    "Partner calls Init Session with redirectUri.",
    "Seller logs in, grants access.",
    "Toco issues encrypted credential and redirects."
  ]
}

• 1. Init Onboard Session
• 2. Get Store Credential