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.
# 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// 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'
)
)
// => 5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05Test 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:
| Field | Value |
|---|---|
| Email address | analyst@example.com |
| Authorization private key (test key) | 415df33775fcee39d464e381aef9e21daee1e61d2cdc5f2f66cf188b5f3a8f03 |
| Authorization public key (test key) | 01e2dd1324317845a8cbac08a1f1709e634dc393e365bbc5dd29fc2bd2b6b69e |
| Signature | 5244b49f1049d260c230a36a0b91addbe1d906c10ae43c8e0a309c216f776fb09ac4c33e2062c72192ca0e38d3961cb15a7ed5347322b8ad64d45f5f4e52bc05 |
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:
| Field | Value |
|---|---|
| Email address | integration@example.com |
| Signature | 18b12d1d89cc2667a346909e56c46899b6fb1729353ece3e9deff7ed28c9c1c0c8ee222a4dfd2075fd2bd2435a9bfcdfe5524ef49cba6680ac3509a00acaa80b |
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:
POST /auth/api/v1/authentication-management/sessionFor the full request and the tokens it returns, see Authorizing an account.