Menu
Cart

FrontEnd Headless API

FrontEnd API communication

1. Initial API Request and Session Creation

  • Client Initiates: The client sends an initial request to the server with a query parameter, apitoken=refresh, to signal that a new session should be created. This request is typically made without any specific session or token information.

  • Server Response: The server responds with:

    • Header: apitoken containing a custom JWT-like, a base64-encoded with session information (sessionId, expires, signKey).

    • Header: nonce, which will be used in subsequent requests to confirm the session's validity.

2. Decoding the Token

  • Client Decodes Token:

    • The client decodes the apitoken header, converting the base64 string into a JSON object.

    • The client stores the nonce header.

    • Extracts the fields: sessionId, expires, and signKey.

3. Nonce Handling

  • Client Stores and Updates nonce:

    • The nonce value is used to protect against replay attacks.

    • On each request, the client updates the nonce value from the server response header and sends it back to the server on the next request as part of the session.

4. Session Signing with Public Key

  • Hashing Steps:

  1. Temporary Hash Creation: The client concatenates the PUBLIC_KEY (configured both in the client app and server) with the signKey received from the server.

const tempHash = PUBLIC_KEY + signKey;

 

  1. Final Hash Creation: The client uses the temporary hash and sessionId to create a SHA-256 hash.

const finalHash = crypto.subtle.digest('SHA-256', new TextEncoder().encode(tempHash + sessionId));

  • Store consumer Key: The client stores the result of the final hash (the consumer key) as long as the sessionId remains the same. This consumer key is added to the token before sending it back to the server.

  • Rebuilding the Token:

    The client adds the consumer key to the JSON object containing the session data and converts it back to base64.

  • The token is then sent back to the server in subsequent requests to maintain the session.

  •  

5. Handling Sensitive Operations (e.g., Login)

  • Login Signature:

    • For highly secure operations such as a login, the client generates a SHA-256 hash using the following:

const loginSignature = crypto.subtle.digest('SHA-256', new TextEncoder().encode(password + email + PUBLIC_KEY));

  • This signature is included as a field in the login request to validate the identity securely.

Summary of Client-Side Process:

  1. Send initial request with apitoken=refresh.

  2. Decode the apitoken header to retrieve sessionId, expires, nonce, and signKey.

  3. Store and update nonce on each request.

  4. Sign the session using PUBLIC_KEY and signKey to generate the consumer key.

  5. Include the consumer key in the token for verification in future requests.

  6. Recalculate the consumer key when the sessionId changes.

  7. Generate and include a signature for secure operations like login.