Skip to content

docs: simplify the email signature guide - #86

Merged
Cre-eD merged 3 commits into
mainfrom
docs/simplify-email-signature-guide
Aug 17, 2026
Merged

docs: simplify the email signature guide#86
Cre-eD merged 3 commits into
mainfrom
docs/simplify-email-signature-guide

Conversation

@Cre-eD

@Cre-eD Cre-eD commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Why

New API users get stuck on the signature field of the authorization request. The signing tutorial presented it as an SDK-specific operation, and its JavaScript example printed the signature of the unhashed email address, so anyone comparing their own output against the documented one concludes their implementation is broken.

What changed

Signing user email addresses rewritten:

  • States the construction up front: signature = Hex( Ed25519-Sign( authPrivateKey, BLAKE2b-256( UTF-8(email) ) ) ).
  • Leads with Python and Node.js examples that need one common dependency each, no blockchain SDK. Both were executed as written and return the documented signature.
  • Keeps a Kotlin/Java example and notes that the SDK hashes the payload internally, which is why it receives the email address as raw bytes.
  • Replaces the incorrect example output with a verified one, and adds a test vector (public example data) so an implementation can be checked before it is pointed at the API.
  • Adds the two things that most often cause a 422: signing with the Blockchain key pair instead of the Authorization one, and passing a 128-character private key.

Authorizing an account: notes that signature and authPublicKeyHex must come from the same Authorization key pair.

Web App UI: notes that a 128-character private key on the Profile screen is the private key followed by the public key, and that only the first 64 characters are the private key.

Calling API endpoints: points users who only need to upload, flag or download data at the Web App, which requires no code.

Verification

  • pnpm docs:build, pnpm format:check and pnpm lint pass locally.
  • Python and Node.js snippets extracted verbatim from the page and executed: both return 57e711...e630a, matching the test vector and the documented output.

The signature required for API authorization is a standard Ed25519
signature over the BLAKE2b-256 hash of the email address, so state the
formula plainly and lead with examples that need no blockchain SDK.
Add a test vector so an implementation can be checked before it is
pointed at the API.

The previous JavaScript example printed the signature of the unhashed
email address, which is not what the endpoint verifies.

Also document two things that were missing: the Profile screen shows
the private key concatenated with the public key, and the Authorization
key pair is the one to sign with.

Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
@Cre-eD
Cre-eD force-pushed the docs/simplify-email-signature-guide branch from 073b931 to cf6f043 Compare August 17, 2026 19:00
The pinned third-party action ships Vercel CLI 25.1.0, and the deploy
endpoint now rejects anything older than 47.2.2, so every branch push
failed. Call the CLI directly at a current release instead, and move
the job off the end-of-life Node 18 runtime.

Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
The Vercel project is still set to Node 18, which the platform has
discontinued, so the build fails before it starts. Declare the version
in the manifest, where it takes precedence over the project setting.

Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
@Cre-eD
Cre-eD merged commit 8cfe6fa into main Aug 17, 2026
2 checks passed
@Cre-eD
Cre-eD deleted the docs/simplify-email-signature-guide branch August 17, 2026 19:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants