Skip to content

Signing user email addresses ​

Every API request to sign in requires a signature of the user's email address.

The signature is a standard Ed25519 signature over the hashed email address, encoded as a Hex string:

digest      = BLAKE2b-256( UTF-8(email) )
digest[31] |= 1
signature   = Hex( Ed25519-Sign( authPrivateKey, digest ) )

Any cryptographic library that provides Ed25519 and BLAKE2b-256 can produce it, in any programming language. No SDK is required.

THE LAST BYTE OF THE DIGEST

Setting the low bit of the digest's last byte is required. It is part of how the hash is represented, and a signature made without it is rejected with a 401 response (InvalidSignature).

It changes the digest for roughly half of all addresses, and leaves the other half untouched, so an implementation that omits it passes for some addresses and fails for others. Check yours against both test vectors below: the first one exercises this bit.

KEYS TO USE

Sign with the authorization key pair, not with the signing one. Both key pairs are shown on the web app Profile page, as Authorization key and Signing key. For details, see Profile and security.

A private key is 64 hexadecimal characters long. Some tools write it with the public key appended, as a 128-character string. If the key you have is 128 characters, its first 64 characters are the private key.

A signature made with the wrong key pair is rejected with a 401 response (InvalidSignature).

Examples ​

The examples below sign the address analyst@example.com with the test key pair.

python
# pip install cryptography
import hashlib

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey


def sign_email(email: str, auth_private_key_hex: str) -> str:
    # A 128-character key is the private key followed by the public key.
    key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(auth_private_key_hex[:64]))
    digest = bytearray(hashlib.blake2b(email.encode("utf-8"), digest_size=32).digest())
    digest[31] |= 1
    return key.sign(bytes(digest)).hex()


print(sign_email(
    "analyst@example.com",
    "415df33775fcee39d464e381aef9e21daee1e61d2cdc5f2f66cf188b5f3a8f03",
))
# => 5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05
js
// npm install @noble/hashes
import { createPrivateKey, sign } from 'node:crypto'
import { blake2b } from '@noble/hashes/blake2.js'

// DER header that turns 32 raw key bytes into a PKCS#8 Ed25519 key
const PKCS8_ED25519_PREFIX = '302e020100300506032b657004220420'

/**
 * @param {string} email
 * @param {string} authPrivateKeyHex - a 128-character key is the private key
 *                                     followed by the public key
 * @returns {string} - email signature hex
 */
function signEmail(email, authPrivateKeyHex) {
  const key = createPrivateKey({
    key: Buffer.from(
      PKCS8_ED25519_PREFIX + authPrivateKeyHex.slice(0, 64),
      'hex'
    ),
    format: 'der',
    type: 'pkcs8'
  })

  const digest = Buffer.from(
    blake2b(new TextEncoder().encode(email), { dkLen: 32 })
  )
  digest[31] |= 1

  return sign(null, digest, key).toString('hex')
}

console.log(
  signEmail(
    'analyst@example.com',
    '415df33775fcee39d464e381aef9e21daee1e61d2cdc5f2f66cf188b5f3a8f03'
  )
)
// => 5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05

Test vector ​

Before you call the API, check your implementation against these values. The key pair is a test key made for this page, not the key of a real account:

FieldValue
Email addressanalyst@example.com
Authorization private key (test key)415df33775fcee39d464e381aef9e21daee1e61d2cdc5f2f66cf188b5f3a8f03
Authorization public key (test key)01e2dd1324317845a8cbac08a1f1709e634dc393e365bbc5dd29fc2bd2b6b69e
Signature5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05

The digest of that address ends in an even byte, so the last-byte rule changes it. The digest of the address in this second vector, same key pair, already ends in an odd byte:

FieldValue
Email addressintegration@example.com
Signature18b12d1d89cc2667a346909e56c46899b6fb1729353ece3e9deff7ed28c9c1c0c8ee222a4dfd2075fd2bd2435a9bfcdfe5524ef49cba6680ac3509a00acaa80b

Ed25519 signatures are deterministic, so a correct implementation returns exactly this signature.

Using the signature ​

Send the resulting Hex string as the signature field of the authorization request:

http
POST /auth/api/v1/authentication-management/session

For the full request and the tokens it returns, see Authorizing an account.