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 log-in request (Account Owner or Account Manager for the given Account). 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:

When App Verification is enabled for your Lens App, the Lens API signs each social operation (e.g., post, comment, follow) using the signing key you provided via the Authorization Endpoint. This signature is included in the operation request sent to the Lens Protocol.

The Lens Protocol validates the signature and executes the operation only if the signature is valid. This process ensures that only operations authorized by your app are executed, providing a secure and reliable way to associate each operation with your app.

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.

First, create an Authorization Endpoint as a publicly accessible HTTPS URL. It must accept POST requests with a JSON body and use token authentication via the standard Authorization header (Bearer token authentication). Ensure the endpoint responds within 500 ms, as exceeding this limit will result in the user’s authentication request being denied.

To ensure reliability, focus on lightweight checks and avoid resource-intensive operations. For more complex validations, consider asynchronously populating a cache with the required data (e.g., through a separate job) to meet the timing constraints. If using serverless infrastructure, address cold start issues to ensure quick 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.comAuthorization: Bearer <secret>Content-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}

Create a secret to be used as a Bearer token for authenticating requests to your Authorization Endpoint.

The secret must be between 64 and 4096 characters and use only type-safe characters, such as:

A–Z a–z 0–9 - _ . ~ + / =

Avoid whitespace, control characters, or symbols that require escaping in HTTP headers.

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"),  bearerToken: "<secret>",});
if (result.isErr()) {  return console.error(result.error);}

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);}

That's it—you now have full control over who can log in into your Lens App and how your sponsorship funds are used.

First, generate a new signing key for the address that will be responsible for signing operations. This key will serve as an authorized App Signer for your Lens App's operations.

cast wallet new
Successfully created new keypair.Address:     0x8711d4d6B7536D…Private key: 0x72433488d76ffec7a16b…

Update the Authorization Endpoint to include the signing key in the response.

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

Then, add address from the previous step to the list of App Signers associated with your Lens App.

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

Finally, enable the App Verification for your Lens App.

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

That's it—all operations performed by the Lens API on behalf of your Lens App will now be signed using the signing key you provided.