ZEzerohash
SDK Authorization

Generate a client access token

Changed on

Generates a temporary JWT access token used to initialize zerohash SDK modules on behalf of one of your end users. The platform authenticates to this endpoint with its own HMAC credentials; the returned JWT is then handed to the end-user client.

Identifying the end user:

  • The Onboarding SDK accepts email to start a fresh onboarding, or participant_code to resume an existing user from where they dropped off. For a retry, send email and participant_code together — zerohash resolves the existing participant and the SDK comes up pre-filled (it is not participant_code alone).
  • To open the Onboarding SDK for tax certification only (onboardingFlow: "tax_only") for a user who is already onboarded, send participant_code with the update-participant permission. See the Onboarding SDK - Tax certification only example.
  • All other SDK experiences require participant_code (the user already exists).

Choosing a variant: the request body is an anyOf — pick the variant matching the SDK experience you are launching, set permissions accordingly, and include only that variant’s fields.

💡 Use the schema dropdown / per-variant examples on the request body below to load a ready-made payload for each experience.

Auto-revoke previous token (optional, off by default): when zerohash enables this setting for your platform, issuing a new client access token for a participant_code automatically revokes the token previously issued for that same participant. The previous token is rejected on its next request (403, JWT token is revoked) — immediately, with no grace period. Revocation is scoped to the {platform, participant} pair. /revoke_auth_token keeps working independently. Leave the setting off if your integration relies on multiple concurrent tokens per participant; contact your zerohash representative to enable it.

post/client_auth_token

Request

  • Base URL
    https://api.cert.zerohash.com
  • URL
    https://api.cert.zerohash.com/client_auth_token
  • Auth
    API key in header X-SCX-API-KEY and API key in header X-SCX-PASSPHRASE

Headers

X-SCX-SIGNEDstring required

HMAC-SHA256 signature of the request, base64-encoded. See the Authentication guide for the exact signing formula.

X-SCX-TIMESTAMPstring required
Example:1678901234

Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.

Request body

OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR

Example request

{
  "permissions": [
    "onboarding"
  ],
  "reference_id": "a81bc81b-dead-4e5d-abff-90865d1e13b1",
  "email": "jane.doe@example.com"
}

Response

Client access token successfully generated.

OR
OR

Example response

{
  "message": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBsaWNhdGlvbl9pZCI6IiIsImRldmljZV9pZCI6IiIsImV4cCI6MTc2MzAyMjA0OCwiaXNzIjoiMmM5YTkxOGUtMGZiMy00YjQ3LTkxZWMtYmVmYTYyZjNhNTJmIiwianRpIjoiZmRjNzEyZTYtZGI1NC00ZjU2LWFhYTAtYWFmOWJlMDZkNDE2IiwicGFydGljaXBhbnRfY29kZSI6IlhCWUMwMCIsInBheWxvYWQiOnsiZGVwb3NpdF9kZXRhaWxzIjp7ImFjY291bnRfbGFiZWwiOiJtYW51YWxfY29udmVyc2lvbl90ZXN0In0sInBhcnRpY2lwYW50X2NvZGUiOiJYQllDMDAiLCJwbGF0Zm9ybV9hZ3JlZW1lbnRfbGluayI6ImliaW50ZXJuYWwiLCJwbGF0Zm9ybV9uYW1lIjoiQUNNRSBMaW1pdGVkIn0sInBlcm1pc3Npb25zIjpbImZ3YyJdLCJwbGF0Zm9ybV9jb2RlIjoiN1NSSzdPIn0.VNlHcBoDQBXRm0w6v-JGDYQaG8hAAUuISMf80v8e_MgLmAFAwB2wQn3yWVTMmoQzKRU1hnnLYqEPcftHVkCK8qGUNuEqeGbSTAd8yBXBFLXw1HnpjNtuZc8tSdp_lVZs2YDvNv-hjXX3-Nbn9g_1VAdDfaJDl3RiarsI3eoX9MYWaM40wKK4kNEQgmXXgcBeWnvLpGoewXh9Udpe7G7mDPD-4n4gp83-V2SBDBXCATfwev8wbpCMTqRgK_8i3U4-xM2hXGchM7TVw6lOEB_Dsh7mPGTT_0tFjl-TeyZ9VKQwWlJkRpgyUedk9ivEHlpe68fw0q4Gl5jEPj3ujgDRsdGuK4CV-xmoHvJLtUqYZHQ30BJ2Bpq1MbpvkQFIBKSvt4Ce3HUZW16V5yeZWh3rAulOPKxBx0rhedWyjRQzXjHduLVRvMw65-a-qLnUDCFAHOuiIZxQvIq-82EESOomFF8RMlo1z_r8fE_6MP37loLSYKsPB-mJBgN0FvrBxZ9k6idm94rozBXckHhOX8gGvzlKk6AZlqaKdrOo1ym0Epqy20tNdcH3oN69j2sTOdJL0PZ7Wto0IhJm9aEiYIRNqdz9oOgoW2ywO7LbLW4iwyH8IGCFefH6gwtrjSRo29JOZDu-exHI_r9_fiCBP9859iUJyPQCAQMHrNbhAZ_B_pE"
  }
}

Changes

  • 47cf70ae701cRevision changes
    • breaking

      removed subschema #2: Account Funding SDK - Deposits subschema #3: Account Funding SDK - Account Link subschema #4: Account Funding SDK - Withdrawals subschema #5: Participant Profile SDK subschema #6: Payins SDK subschema #7: Crypto Withdrawals SDK subschema #8: Crypto Payouts SDK subschema #9: Crypto Buy SDK subschema #10: Crypto Sell SDK from the request body oneOf list

    • info

      added subschema #1: Onboarding SDK - New user (email) subschema #2: Onboarding SDK - Existing user (resume / retry) subschema #3: Onboarding SDK - Tax certification only (existing participant) subschema #4: Update Participant subschema #5: Account Funding SDK - Deposits subschema #6: Account Funding SDK - Account Link subschema #7: Account Funding SDK - Withdrawals subschema #8: Fiat Deposit SDK subschema #9: Fiat Withdraw SDK subschema #10: Fiat Account Link SDK subschema #11: Participant Profile SDK subschema #12: Payins SDK subschema #13: Crypto Deposits SDK subschema #14: Crypto Withdrawals SDK subschema #15: Crypto Payouts SDK subschema #16: Crypto Buy SDK subschema #17: Crypto Sell SDK to the request body anyOf list