Initiate Registration

To register a user with Passkeys using the API you first need to make sure you have the values for your request headers set up by following the Unauthenticated Requests setup guide.

Once you have your values for x-scope-id and x-encrypted-key setup. You can now initiate a user registration.

The initiateRegistration method initiates the user registration process within a specific scope. It generates a registration challenge that the user must solve to proceed with their registration.

HTTP Method: POST

• Headers

  • X-Scope-Id: A UUID string representing the application scope.

  • X-Encrypted-Key: A string containing the encrypted key for secure communication.

• Body:

  • encrypted_user: String - A base64-encoded string containing encrypted user data.

The encrypted_user is generated by RSA encrypting the user parameters with the non-encrypted AES key you generated when following Unauthenticated Requests, and by using the following aesEncrypt function.

const aesEncrypt = async (
  plainText: string,
  encryptionKey: BufferSource,
  keyFormat: "raw" = "raw",
  keyLength: number = 256
) => {
  if (!encryptionKey) {
    throw Error("Encryption key not initialized");
  }

  const encoder = new TextEncoder();
  const data = encoder.encode(plainText);
  let cryptoKey: CryptoKey;
  let encrypted: ArrayBuffer;

  try {
    cryptoKey = await importKey(keyFormat, encryptionKey, { name: "AES-GCM", length: keyLength }, [
      "encrypt",
    ]);

    const iv = cryptoObj.getRandomValues(new Uint8Array(12)); // Initialization vector
    
    // Same encrypt function from "Unauthenticated Requests" guide.
    encrypted = await encrypt({ name: "AES-GCM", iv }, cryptoKey, data);

    const combined = new Uint8Array(iv.length + encrypted.byteLength);
    combined.set(iv, 0);
    combined.set(new Uint8Array(encrypted), iv.length);

    return btoa(String.fromCharCode.apply(null, combined));
  } catch (error) {
    console.error("AES-GCM Encryption error:", error);
    throw error;
  }
};

Now we can encrypt our user parameters and pass that value as our encrypted_user in our API request.

const params = {
    username: "test_user",
    userDisplayName: "test_user"
}

// Same aesKey created with `generateAesKey`
const encrypted_user = await aesEncrypt(JSON.stringify(params), aesKey);

Response Spec

• challenge_id: String - A UUID that uniquely identifies the registration challenge.

• encrypted_creation_challenge: String - A base64-encoded string representing the encrypted challenge that the user must solve to proceed with registration.

Request Example

POST / HTTP/1.1
Host: tiramisu.0xpass.io
Content-Type: application/json
x-scope-id: 123e4567-e89b-12d3-a456-426614174000
x-encrypted-key: jp6t2GVOvzltN+4VGc21ZKPIbLjEvitE34cFYDvVNrcmF2ukcKMTO8R/F0wbonGZM0NZBg2X94FvirH6Hi2U1zFlXN5srkOdvQL3lVNZ86gbfEtJFPOEAeZkxtTOKOsH4ZXPtUbFOjT2Niblo8njOKibOoAMRKIhtsNTTvRXjHRxnNqVs3QcSe7XbO1DbH/pdRgq+YZN13znlSRsupu4G/h/KBEZr98wXFo8PeDV9F8ZV56F90GqQ3wKzFUBwC9rJihGz0omH+eJA0jB/K7BYt30fhWDnqaLNP2eb1mbIjBCmv6sXqu2jtghr3ejl0YwjP9lCO+aVD7bophfb/IyKg==

{
    "jsonrpc": "2.0",
    "method": "initiateRegistration",
    "params": {
        "encrypted_user": "JZVjZw33OGoQDEMcbOdckx4TzspQEKP5j+iAGqf6b6gPleziY/Noyd4uW6KMSujq0HKP2Rb69p9Wi8ic5O8LZl9oTmmWk4op0CUKejqcV5DsNDp83PYzUg=="
    },
    "id": 1
}

Response Example

{
    "jsonrpc": "2.0",
    "result": {
        "challenge_id": "e0f8cbee-6d64-4a9b-af88-3d73a8b95b34",
        "encrypted_creation_challenge": "JZVjZw33OGoQDEMcbOdckx4TzspQEKP5j+iAGqf6b6gPleziY/Noyd4uW6KMSujq0HKP2Rb69p9Wi8ic5O8LZl9oTmmWk4op0CUKejqcV5DsNDp83PYzUg=="
    },
    "id": 1
}