Authorization Workflows

During the initial authentication, the Lens API makes a server-to-server call to a custom Authorization Endpoint that you define. This call containing information about the user’s Lens Account and the address that is signing the request. Based on this information, the endpoint determines whether the user is allowed acquire credentials for the Lens API as a user of your Lens App.

The endpoint response can also control:

Optionally, for each social operation (e.g., post, comment, follow), the Lens API makes a server-to-server call to a custom Verification Endpoint that you define and configure in the previous step.

This call includes details about the operation and the user’s Lens Account. The endpoint evaluates this information and determines whether to approve the operation by returning a cryptographic signature.

When the user's credentials are about to expire and the client requests a refresh, the Lens API makes a server-to-server call to the Authorization Endpoint to determine if the user is still allowed to act as a user of your Lens App.

The Authorization Endpoint must be a publicly accessible HTTPS URL accepting POST requests with a JSON body. The Lens API allows a maximum of 500ms for a response; delays beyond this will deny the user’s authentication request.

To ensure reliability, prioritize lightweight checks and avoid heavy operations. For complex validations, asynchronously populate a cache with necessary data (e.g., via a separate job) to meet timing requirements. If using serverless infrastructure, mitigate cold starts to ensure prompt responses.

Request

The Lens API will send a POST request to the Authorization Endpoint according to the following format:

POST /path/to/endpoint HTTP/1.1Host: myserver.comContent-Type: application/json{  "account": "0x4F10f685B6BF165e86f41CDf4a906B17F295C235",  "signedBy": "0x00004747f7a56EE7Af7237220c960a7D06232626"}

Response

The Authorization Endpoint must respond with a JSON object according to the following format:

HTTP/1.1 200 OKContent-Type: application/json{  "allowed": true,  "sponsored": true}

Once you have your Authorization Endpoint ready, you can configure it for your Lens App.

import { evmAddress, uri } from "@lens-protocol/client";import { addAppAuthorizationEndpoint } from "@lens-protocol/client/actions";

const result = await addAppAuthorizationEndpoint(sessionClient, {  endpoint: uri("https://myserver.com/path/to/endpoint"),  app: evmAddress("0xa0182D914845ec1C3EF61a23C50D56370E23d94e"),});
if (result.isErr()) {  return console.error(result.error);}

You can revert this configuration at any time.

import { evmAddress } from "@lens-protocol/client";import { removeAppAuthorizationEndpoint } from "@lens-protocol/client/actions";

const result = await removeAppAuthorizationEndpoint(sessionClient, {  app: evmAddress("0xa0182D914845ec1C3EF61a23C50D56370E23d94e"),});
if (result.isErr()) {  return console.error(result.error);}

First, create a Verification Endpoint to handle the Operations Approval mechanism.

The Verification Endpoint must be a publicly accessible HTTPS URL that accepts POST requests with a JSON payload and responds within 500ms; delays will cause the request to be treated as invalid. Like the Authorization Endpoint, optimize its performance by using caching or pre-computed data where necessary and ensure reliable hosting to avoid downtime or delays.

Request

The Lens API will send a POST request to the Verification Endpoint according to the following format:

POST /path/to/endpoint HTTP/1.1Host: myserver.comContent-Type: application/json{  "nonce": "42",  "deadline": "1630000000",  "operation": "Post",  "account": "0x4F10f685B6BF165e86f41CDf4a906B17F295C235"}

Possible values for the operation field are:

enum Operation {  Post  Repost  EditPost  DeletePost  Follow  Unfollow  CreateAccount  CreateUsername  CreateAndAssignUsername  AssignUsername  UnassignUsername  SetAccountMetadata  JoinGroup  LeaveGroup}

Response

The Verification Endpoint must respond with a JSON object according to the following format:

HTTP/1.1 200 OKContent-Type: application/json{  "allowed": true,  "signature": "0x2b8a91ad7b6db0c29a09d592e8f16287b82a40a6d245cb3e1f174b02d0fb08a2"}

Then, implement the signing logic within your Verification Endpoint to handle operation approvals.

The Verification Endpoint must return an EIP-712 signature as cryptographic proof that the app has approved the operation. The example below demonstrates how to generate this signature using viem and TypeScript.

import { walletClient } from "./config";import { domain, types } from "./data";
const signature = await walletClient.signTypedData({  domain,  types,  primaryType: "SourceStamp",  message: {    // your Lens App contract address    source: "0x75bb5fBdb559Fb2A8e078EC2ee74aad791e37DCc",    nonce: "<request-body-nonce>",    deadline: "<request-body-deadline>",  },});

Then, add the approver address to the list of App Signers associated with your Lens App.

import { evmAddress } from "@lens-protocol/client";import { addAppSigners } from "@lens-protocol/client/action";
const result = await addAppSigners(sessionClient, {  app: evmAddress("0x75bb5fBdb559Fb2A8e078EC2ee74aad791e37DCc"),  signers: [evmAddress("0xe2f2a5C287993345a840db3B0845fbc70f5935a5")],});

import { handleWith } from "@lens-protocol/client/viem";
// …
const result = await addAppSigners(sessionClient, {  app: evmAddress("0x75bb5fBdb559Fb2A8e078EC2ee74aad791e37DCc"),  signers: [evmAddress("0xe2f2a5C287993345a840db3B0845fbc70f5935a5")],}).andThen(handleWith(walletClient));

Finally, enable the App Verification for your Lens App.

import { evmAddress } from "@lens-protocol/client";import { addAppSigners } from "@lens-protocol/client/action";
const result = await setAppVerification(sessionClient, {  app: evmAddress("0x75bb5fBdb559Fb2A8e078EC2ee74aad791e37DCc"),  enabled: true,});

import { handleWith } from "@lens-protocol/client/viem";
// …
const result = await setAppVerification(sessionClient, {  app: evmAddress("0x75bb5fBdb559Fb2A8e078EC2ee74aad791e37DCc"),  enabled: true,}).andThen(handleWith(walletClient));

That's it—only legit operations signed by your Verification Endpoint will succeed.