Authentication

This guide will help you understand how to handle authentication in Lens.

The Lens API uses authentication roles to define different levels of access and interaction:

To log in to Lens, end-user roles such as Account Owner, Account Manager, or Onboarding User need to know the EVM address of the App they want to connect to. The Builder role does not require an app address for authentication.

mutation {  challenge(    request: {      accountOwner: {        app: "<app-address>"        account: "<account-address>"        owner: "<owner-address>"      }    }  ) {    __typename    id    text  }}

{  "data": {    "challenge": {      "id": "<challenge-id>",      "text": "<origin-domain> wants you to sign in with your Ethereum account…"    }  }}

import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.APP_PRIVATE_KEY);
const signature = account.signMessage({ message });

mutation {  authenticate(request: { id: "<challenge.id>", signature: "<signature>" }) {    ... on AuthenticationTokens {      accessToken      refreshToken      idToken    }
    ... on WrongSignerError {      reason    }
    ... on ExpiredChallengeError {      reason    }
    ... on ForbiddenError {      reason    }  }}

Often, when you are about to log in with an Account, you may want to list the available Accounts for the user's wallet.

query {  accountsAvailable(    request: { managedBy: "<wallet-address>", includeOwned: true }  ) {    items {      ... on AccountManaged {        account {          address          username          metadata {            name            picture          }        }        permissions {          canExecuteTransactions          canTransferTokens          canTransferNative          canSetMetadataUri        }        addedAt      }      ... on AccountOwned {        account {          address          username          metadata {            name            picture          }        }        addedAt      }    }    pageInfo {      prev      next    }  }}

Continue with the Pagination guide for more information on how to handle paginated results.

Once you have successfully authenticated, you can manage your authenticated session by:

mutation {  refresh(request: { refreshToken: "<refresh-token>" }) {    ... on AuthenticationTokens {      accessToken      refreshToken      idToken    }
    ... on ForbiddenError {      reason    }  }}

query {  currentSession {    authenticationId    app    browser    device    os    origin    signer    createdAt    updatedAt  }}

query {  authenticatedSessions(    request: {      # app: "<app-address">, You can filter by app address      pageSize: TEN    }  ) {    items {      authenticationId      app      browser      device      os      origin      signer      createdAt      updatedAt    }    pageInfo {      prev      next    }  }}

See the Pagination guide for more information on how to handle paginated results.

mutation {  revokeAuthentication(request: { authenticationId: "<authentication-id>" })}

Lens API uses JSON Web Tokens (JWT) as format for Token-Based authentication.

On successful authentication, Lens API issues three tokens:

Lens JWTs are signed with the RS256 algorithm and can be verified using JSON Web Key Sets (JWKS) from the /.well-known/jwks.json endpoint on the corresponding Lens API environment (e.g., <coming-this-week>/.well-known/jwks.json for testnet).

Access Tokens are used to authenticate a user's identity when making requests to the Lens API.

The Access Token is required in the Authorization or x-access-token header for all authenticated requests to the Lens API.

Authorization: Bearer <access-token># orx-access-token: <access-token>

Lens Access Tokens are valid for 10 minutes from the time of issuance.

A Refresh Token is a credential artifact used to obtain a new authentication tokens triplet without user interaction. This allows for a shorter Access Token lifetime for security purposes without involving the user when the access token expires. You can request new authentication tokens until the refresh token is added to a denylist or expires.

Lens Refresh Tokens are valid for 7 days from the time of issuance.

The ID Token is used to verify the user's identity on consumer's side. It contains a set of claims about the user and is signed by the Lens API.

Lens ID Tokens are valid for 10 minutes from the time of issuance, same as the Access Token.

As briefly mentioned earlier, Lens ID Tokens can be used to verify's user identity on a backend service.

Lens ID Tokens are issued with the following claims:

A typical use case is to use Lens issued ID Token to verify the legitimacy of user's request before issuing your app specific credentials. The following diagram illustrates this flow:

Below is an example of a Next.js middleware that demonstrates how to verify a Lens ID Token using the popular jose library:

import { NextResponse } from "next/server";import { jwtVerify, createRemoteJWKSet } from "jose";
// Get JWKS URI from environment variablesconst jwksUri = process.env.NEXT_PUBLIC_JWKS_URI;const JWKS = createRemoteJWKSet(new URL(jwksUri));
export async function middleware(req) {  const token = req.headers.get("authorization")?.split(" ")[1];
  if (!token) {    return new NextResponse(      JSON.stringify({ error: "Authorization token missing" }),      {        status: 401,        headers: { "Content-Type": "application/json" },      }    );  }
  try {    // Verify the JWT using the JWKS    const { payload } = await jwtVerify(token, JWKS);
    // Optionally, attach the payload to the request    req.user = payload;
    // Proceed to the API route    return NextResponse.next();  } catch (error) {    console.error("JWT verification failed:", error);    return new NextResponse(      JSON.stringify({ error: "Invalid or expired token" }),      {        status: 401,        headers: { "Content-Type": "application/json" },      }    );  }}
export const config = {  matcher: ["/api/:path*"],};

The example works under the following assumptions:

Adapt it to your specific use case as needed.

You can now use the req.user object in your API routes to access the user's identity.

export default function handler(req, res) {  // The JWT payload will be available as req.user if the token is valid  if (req.user) {    return res.status(200).json({ message: "Success", user: req.user });  } else {    return res.status(401).json({ error: "Unauthorized" });  }}