Initiate Authentication

To use initiateAuthentication method via 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 authentication.

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.

  • X-Encrypted-User: The user input encrypted using the encryption key

• Body:

  • regenerate_seed: A boolean indicating whether to regenerate the seed for the session.

  • encrypted_user: A string representing the encrypted user information.

  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: A unique identifier for the authentication challenge.

• encrypted_request_challenge: A string representing the encrypted challenge that the user must respond to.

Request Example

POST / HTTP/1.1
Host: https://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==
X-Encrypted-User: JZVjZw33OGoQDEMcbOdckx4TzspQEKP5j+iAGqf6b6gPleziY/Noyd4uW6KMSujq0HKP2Rb69p9Wi8ic5O8LZl9oTmmWk4op0CUKejqcV5DsNDp83PYzUg==
{
  "jsonrpc": "2.0",
  "method": "initiateAuthentication",
  "params": {
    "regenerate_seed": true,
    "encrypted_user": "JZVjZw33OGoQDEMcbOdckx4TzspQEKP5j+iAGqf6b6gPleziY/Noyd4uW6KMSujq0HKP2Rb69p9Wi8ic5O8LZl9oTmmWk4op0CUKejqcV5DsNDp83PYzUg=="
  },
  "id": 1
}

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "result": {
    "challenge_id": "456e4567-e89b-12d3-a456-426614174000",
    "encrypted_request_challenge": "JZVjZw33OGoQDEMcbOdckx4TzspQEKP5j+iAGqf6b6gPleziY/Noyd4uW6KMSujq0HKP2Rb69p9Wi8ic5O8LZl9oTmmWk4op0CUKejqcV5DsNDp83PYzUg=="
  },
  "id": 1
}