📲Method 3: Passkey

Passkey authentication with Lighthouse provides a secure, passwordless authentication mechanism using WebAuthn. This involves registering a passkey tied to a wallet address and then authenticating with the registered credential. Below are the endpoints and steps for both registration and login.

Overview of WebAuthn API Endpoints

Registration - Register a new passkey credential for a user’s wallet address.
Authentication - Authenticate an existing user with a registered passkey credential.
Delete Credential - Remove an existing credential associated with a wallet address.

1. Registration

To register a new passkey credential for a user, follow these two steps:

A. Start Registration

This endpoint initiates the registration process by generating a challenge. The challenge is required for creating the WebAuthn credential using the navigator.credentials.create() function on the frontend.

Endpoint:

https://encryption.lighthouse.storage/passkey/register/start

Method:

POST

Headers:

"Authorization": "Bearer <Your_Signed_Message_Token>"

Request Body Parameters:

address: The user's wallet address.

Success Response:

Code: 200 OK

Content example:

{
  "challenge": {
    "data": "[Array of challenge data]"
  },
  "user": {
    "id": "[Array of user ID data]",
    "name": "<WalletAddress>",
    "displayName": "<WalletAddress>"
  }
}

Use the returned challenge and user data in the WebAuthn registration process on the client side.

B. Finish Registration Endpoint

This endpoint completes the registration process by validating the credential data. After verification, the credential is associated with the provided wallet address.

Endpoint:

https://encryption.lighthouse.storage/passkey/register/finish

Method:

POST

Request Body Parameters:

address (string): Wallet address to prove ownership. (e.g., 0x254511193Dd29f9c3c474c43B8d23C3d367Bc4A8 )
data (object): Contains WebAuthn credential details generated during the navigator.credentials.create() process.
- authenticatorAttachment: The modality of the selected authenticator (e.g., "cross-platform").
- id: Credential ID generated by the authenticator (e.g., "Af_Afcbl3pONtRLg...kU-R0").
- rawId: Raw credential ID (e.g., "Af_Afcbl3pONtRLg...kU-R0").
- response: Object with attestation details.
  - attestationObject: Contains attestation data for the public key credential (e.g., "o2NmbXRkbm...TNsqfc0sY").
  - clientDataJSON: JSON data from the client, including the challenge (e.g., "eyJ0eXBlIj...NzI6MzAwMCIsImNyb3NzT3JpZ2luIjpmYWxzZX0").
- type: Credential type, usually "public-key".
signature (string): Signature generated from a previously signed message.
name (optional, string): A label for the credential.

Success Response:

Code: 200 OK

Content:

true

A response of true indicates successful registration with WebAuthn. Send the credential data obtained from navigator.credentials.create() to finalize registration. Ensure that the signed message is valid and that all data is securely handled.

Error Responses

400 Bad Request: Invalid data or address format.
401 Unauthorized: Invalid or expired signed message.
500 Internal Server Error: Server error; try again later.

2. Authentication

To authenticate a registered user, perform the following steps:

A. Start Authentication

This endpoint initiates the authentication process by generating a new challenge, which is required to invoke the navigator.credentials.get() method on the frontend.

Endpoint:

https://encryption.lighthouse.storage/passkey/login/start

Method:

POST

Request Body Parameters:

address (string): User’s wallet address.

Success Response:

Code: 200 OK

Content example:

{
  "challenge": {
    "type": "Buffer",
    "data": "[Array of challenge data]"
  },
  "allowCredentials": [
      {
          "credentialID": "<Credential ID>",
          "name": "<User Assigned user Name>"
      }
    ]
}

Content Body Parameters:

challenge:
- type: The type of buffer used. (e.g., "Buffer").
- data: An array of numeric values representing the challenge data.
allowCredentials (Array):
- credentialID: The unique identifier for the WebAuthn credential
- name :This is the Name you are assigning to this credential (Options)

Use the challenge and allowCredentials arrays with the navigator.credentials.get() function to retrieve a credential from the client.

B. Finish Authentication Endpoint

This endpoint completes the authentication by verifying the credential data and generating an authentication token.

Endpoint:

https://encryption.lighthouse.storage/passkey/login/finish

Method:

POST

Request Body Parameters:

credentialID (string): Identifier of the WebAuthn credential.
data (object): Contains details related to the WebAuthn response and authenticator.
- authenticatorAttachment: Describes the attachment modality, e.g., "cross-platform".
- id, rawId: Identifiers for the credential.
- response: Object with WebAuthn response details.
  - attestationObject: The attestation structure after a successful WebAuthn registration.
  - clientDataJSON: A JSON representation of the client data, including the challenge, origin, type, and other details.
  - signature: The signature generated by the authenticator based on the client data.
  - authenticatorData: Contains information about the authentication event, including the counter and sometimes the user handle.
- type: The type of the public key credential, e.g., "public-key".

Success Response:

Code: 200 OK

Content:

{
  "token": "YOUR_AUTHENTICATION_TOKEN"
}

Error Responses

400 Bad Request: Invalid data or address format.
401 Unauthorized: Invalid or expired signed message.
500 Internal Server Error: Server error; try again later.

The returned token can be used for subsequent authenticated requests within the Lighthouse system.

3. Delete Credential

To remove an existing passkey credential associated with a wallet address, use the following endpoint:

Delete Credential Endpoint

This endpoint deletes the specified credential, disassociating it from the provided wallet address.

Endpoint:

https://encryption.lighthouse.storage/passkey/delete

Method:

DELETE

Headers:

Content-Type: application/json
Authorization: Bearer SIGNED_MESSAGE

Request Body Parameters:

address: The Ethereum wallet address associated with the user.
credentialID: The unique identifier for the WebAuthn credential obtained from the start endpoint.

Success Response:

Code: 200

Content: Successful deletion confirmation.

Error Responses

400 Bad Request: Invalid data or address format.
401 Unauthorized: Invalid or expired signed message.
500 Internal Server Error: Server error; try again later.

Use this endpoint to revoke access associated with a specific credential.

Notes & Best Practices

Challenge Handling: Always ensure that challenges are handled securely and not exposed to unauthorized access.
Authorization: Use the Bearer Authorization token (signed message) to authenticate requests. Renew tokens as necessary.
Credential Storage: Each passkey is securely stored and associated with a user’s wallet address for subsequent logins.
Error Management: Check for error responses and handle them accordingly in your application.

Following these guidelines ensures secure, passwordless authentication using passkeys within the Lighthouse ecosystem.

PreviousMethod 2: JWT NextEncryption Features

Last updated 1 month ago