openapi: 3.0.4
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Action AuthAddress API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: AuthAddress
paths:
  /v2/farcaster/auth_address/developer_managed/:
    get:
      description: Fetches the status of a developer managed auth address by auth address
      externalDocs:
        url: https://docs.neynar.com/reference/lookup-developer-managed-auth-address
      operationId: lookup-developer-managed-auth-address
      parameters:
      - description: Ethereum address
        in: query
        name: address
        required: true
        schema:
          example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
          pattern: ^0x[a-fA-F0-9]{40}$
          title: EthAddress
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  address:
                    $ref: '#/components/schemas/EthAddress'
                  auth_address_approval_url:
                    format: uri
                    type: string
                  fid:
                    $ref: '#/components/schemas/Fid'
                  status:
                    enum:
                    - pending_approval
                    - approved
                    - revoked
                    type: string
                required:
                - address
                - status
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Status by auth address
      tags:
      - AuthAddress
  /v2/farcaster/auth_address/developer_managed/signed_key/:
    post:
      description: Allow apps to register an Ethereum addresses as authorized "auth addresses" for a user's Farcaster account, enabling seamless Sign-In With Farcaster (SIWF) across applications without repeated custody wallet authorizations.
      externalDocs:
        url: https://docs.neynar.com/reference/register-signed-key-for-developer-managed-auth-address
      operationId: register-signed-key-for-developer-managed-auth-address
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAuthAddressDeveloperManagedSignedKeyReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  address:
                    $ref: '#/components/schemas/EthAddress'
                  auth_address_approval_url:
                    format: uri
                    type: string
                  fid:
                    $ref: '#/components/schemas/Fid'
                  status:
                    enum:
                    - pending_approval
                    - approved
                    - revoked
                    type: string
                required:
                - address
                - status
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Register Signed Key
      tags:
      - AuthAddress
components:
  schemas:
    EthAddress:
      description: Ethereum address
      example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
      pattern: ^0x[a-fA-F0-9]{40}$
      title: EthAddress
      type: string
    ErrorRes:
      description: Details for the error response
      properties:
        code:
          type: string
        message:
          type: string
        property:
          type: string
        status:
          format: int32
          type: integer
      required:
      - message
      title: ErrorRes
      type: object
    RegisterAuthAddressDeveloperManagedSignedKeyReqBody:
      properties:
        address:
          $ref: '#/components/schemas/EthAddress'
        app_fid:
          $ref: '#/components/schemas/Fid'
        deadline:
          description: unix timestamp in seconds that controls how long the signed key request is valid for. (24 hours from now is recommended)
          type: integer
        redirect_url:
          description: 'Url to redirect to after the signer is approved.

            **Note** : This should only be used when requesting a signer from a native mobile application.'
          type: string
        signature:
          description: Signature generated by the custody address of the app. Signed data includes app_fid, deadline, 32 bytes padded auth address. [Refer guide for more details.](https://docs.neynar.com/docs/auth-address-signature-generation)
          example: '0x16161933625ac90b7201625bfea0d816de0449ea1802d97a38c53eef3c9c0c424fefbc5c6fb5eabe3d4f161a36d18cda585cff7e77c677c5d34a9c87e68ede011c'
          pattern: ^0x[a-fA-F0-9]+$
          type: string
        sponsor:
          $ref: '#/components/schemas/SignedKeyRequestSponsor'
      required:
      - address
      - app_fid
      - deadline
      - signature
      title: RegisterAuthAddressDeveloperManagedSignedKeyReqBody
      type: object
    SignedKeyRequestSponsor:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        signature:
          description: Signature generated by the fid of the sponsor and the signature generated from signKeyRequest for the app.
          type: string
        sponsored_by_neynar:
          description: 'Neynar will sponsor the signer if set to true.

            **Note: ** If sponsor.fid and sponsor.signature are provided along with sponsored_by_neynar set to true,

            the sponsor.fid and sponsor.signature will be ignored.

            Neynar will sponsor the signer on behalf of the user. The developer will get charged in credits.'
          type: boolean
      title: SignedKeyRequestSponsor
      type: object
    Fid:
      description: The unique identifier of a farcaster user or app (unsigned integer)
      example: 3
      format: int32
      minimum: 0
      title: Fid
      type: integer
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS