> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neynar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Farcaster Actions Spec

> Complete specification for Farcaster Actions - enabling secure cross-app communication and actions using Farcaster signers

<Info>
  ### API Endpoints

  Related API reference [Publish Farcaster Action](/reference/publish-farcaster-action)
</Info>

## Introduction

Farcaster Actions is a spec that allows Farcaster applications to securely communicate and perform actions on behalf of users across different apps. It enables an app (referred to as **App A**) to send data or trigger actions in another app (**App B**) on behalf of a mutual user (e.g., **Carol**) by signing messages using the user's Farcaster signer.

This document provides an overview of how Farcaster Actions works and guides developers in implementing this functionality within their Neynar applications.

## Overview of Farcaster Actions

* **Purpose**: Facilitate secure cross-app interactions on behalf of users.

* **Participants**:

  * **User**: The individual (e.g., Carol) who authorizes actions between apps.
  * **App A**: The initiating app requesting to perform an action in App B.
  * **App B**: The receiving app that processes the action from App A.
  * **Neynar API**: The intermediary that assists in signing and forwarding the action securely.

## Workflow

### 1. Requesting Signer Access

**App A** requests a Farcaster signer from the user (**Carol**)

* **User Authorization**: Carol approves the signer.
* **Signer UUID**: Upon approval, App A receives a unique identifier (UUID) for Carol's signer.

### 2. Making an API Call with Signer UUID and Metadata

App A prepares to send an action to App B by making an API call to the Neynar API, including:

* **Signer UUID**: The unique identifier for Carol's signer.
* **Destination base URL**: The base URL of App B where the action should be sent.
* **Action Payload**: An object containing the type of action and any necessary payload data.

### 3. Neynar API Produces a Signature

The Neynar API processes the request from App A:

* **Signature Generation**: Neynar uses Carol's signer to generate a cryptographic signature
* **Bearer Token Creation**: A bearer token is created, encapsulating the signature and additional metadata, which will be used for authentication.

### 4. Forwarding the Signed Message to App B

Neynar forwards the signed action to App B:

* **HTTP Request**: An HTTP POST request is sent to App B's specified endpoint.
* **Headers**: The request includes an `Authorization` header containing the bearer token.
* **Body**: The action payload is included in the request body.

### 5. App B Verifies the Signature

Upon receiving the request, App B performs the following:

* **Signature Verification**: App B verifies the bearer token using Carol's public key and ensures the signature is valid.
* **Farcaster ID (fid)**: The token includes Carol's fid, confirming her identity.
* **Action Processing**: If verification succeeds, App B processes the action and updates its state accordingly.

## Implementation Details

### For App A Developers

<Steps>
  <Step title="Request Signer Access">
    * Checkout the documentation on [managed signers](/docs/integrate-managed-signers)
  </Step>

  <Step title="Prepare the Action Request">
    * Define the action payload, including the type and any necessary data.
    * Specify the destination base URL of App B.
  </Step>

  <Step title="Call the Neynar API">
    * Make a POST request to the Neynar API endpoint (POST - `/v2/farcaster/action`) with the following structure:

    <CodeGroup>
      ```json json theme={"system"}
      {
        "signer_uuid": "uuid-of-the-signer",
        "url": "https://appb.xyz",
        "action": {
          "type": "actionType",
          "payload": {
            // Action-specific data
          }
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Handle the Response">
    * The Neynar API will forward the action to App B and return the response from App B.
    * Ensure proper error handling for cases where the action fails or the signature is invalid.
  </Step>
</Steps>

### For App B Developers

<Steps>
  <Step title="Set Up an Endpoint to Receive Actions">
    * Create an HTTP endpoint to receive POST `/api/farcaster/action`requests from the Neynar API.
    * Ensure the endpoint URL is accessible and secured via HTTPS.
  </Step>

  <Step title="Extract and Verify the Bearer Token">
    * Extract the `Authorization` header from incoming requests.
    * Decode the bearer token to retrieve the header, payload, and signature.
    * Use the fid and public key from the token header to verify the signature against the payload.
  </Step>

  <Step title="Process the Action">
    * Once the signature is verified, extract the action payload from the request body.
    * Perform the necessary operations based on the action type and payload.
    * Update your application's state or database as required.
  </Step>

  <Step title="Respond to the Request">
    * Return an appropriate HTTP response indicating success or failure.
    * Include any necessary data in the response body for App A to process.
  </Step>
</Steps>

## Security Considerations

* **Token Expiration**: The bearer token has a short expiration time (5 minutes) to enhance security.
* **Signer Confidentiality**: Private keys are managed securely by Neynar and are never exposed to apps.
* **Data Integrity**: Signatures ensure that the action payload cannot be tampered with during transit.

## Conclusion

Farcaster Actions provides a secure and efficient way for Neynar apps to interact on behalf of users. By leveraging cryptographic signatures and Neynar's API, apps can ensure that cross-app actions are authenticated and authorized by the user, enhancing trust and interoperability within the Neynar ecosystem.

## Example

### Action Schema

The action request sent to the Neynar API follows this schema:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "signer_uuid": "string (UUID format)",
    "url": "string (valid URL)",
    "action": {
      "type": "string",
      "payload": {
        // Object containing action-specific data
      }
    }
  }
  ```
</CodeGroup>

Sample Request from App A to Neynar API

**POST** `/v2/farcaster/action` **Content-Type:** `application/json`

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "signer_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "url": "https://appb.example.com",
    "action": {
      "type": "sendMessage",
      "payload": {
        "message": "Hello from App A!"
      }
    }
  }
  ```
</CodeGroup>

Forwarded Request from Neynar API to App B

**POST** `/api/farcaster/action` **Content-Type:** `application/json` **Authorization:** `Bearer Token`

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "action": {
      "type": "sendMessage",
      "payload": {
        "message": "Hello from App A!"
      }
    }
  }
  ```
</CodeGroup>

App B would then verify the bearer token and process the action accordingly.