Authentication | Fern Documentation

Authentication in OpenRPC can be configured at the server level or method level, depending on your JSON-RPC implementation. Unlike REST APIs, JSON-RPC typically handles authentication through the transport layer (HTTP headers) or within the JSON-RPC request payload.

HTTP transport authentication

When using HTTP as the transport for JSON-RPC, you can use standard HTTP authentication schemes.

Bearer token authentication

Configure bearer token authentication for HTTP-based JSON-RPC:

openrpc.yml

servers:
  - name: production
    url: https://api.example.com/rpc
    description: Production JSON-RPC server
    security:
      - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

This generates SDK methods that require a token:

const client = new JSONRPCClient({
  url: "https://api.example.com/rpc",
  auth: {
    bearer: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
});
// Call JSON-RPC method
const result = await client.call("calculate.add", { a: 5, b: 3 });

API key authentication

Configure API key authentication:

openrpc.yml

servers:
  - name: production
    url: https://api.example.com/rpc
    description: Production JSON-RPC server
    security:
      - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Usage in SDK:

const client = new JSONRPCClient({
  url: "https://api.example.com/rpc",
  auth: {
    apiKey: "your-api-key-here"
  }
});

Basic authentication

Configure basic authentication:

openrpc.yml

servers:
  - name: production
    url: https://api.example.com/rpc
    description: Production JSON-RPC server
    security:
      - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Usage in SDK:

const client = new JSONRPCClient({
  url: "https://api.example.com/rpc",
  auth: {
    username: "user@example.com",
    password: "password123"
  }
});

Method-level authentication

Some JSON-RPC implementations may require different authentication for specific methods:

openrpc.yml

methods:
  - name: public.getInfo
    summary: Get public information
    description: Publicly accessible method (no auth required)
    params: []
    result:
      name: info
      schema:
        type: object
  - name: user.getProfile
    summary: Get user profile
    description: Requires user authentication
    security:
      - bearerAuth: []
    params:
      - name: userId
        schema:
          type: string
        required: true
    result:
      name: profile
      schema:
        $ref: '#/components/schemas/UserProfile'

WebSocket authentication

For WebSocket transport, authentication typically happens during connection establishment:

openrpc.yml

servers:
  - name: websocket
    url: wss://api.example.com/rpc
    description: WebSocket JSON-RPC server
    variables:
      token:
        description: Authentication token for WebSocket connection
        default: ""
    security:
      - wsAuth: []
components:
  securitySchemes:
    wsAuth:
      type: apiKey
      in: query
      name: token
      description: Authentication token passed as query parameter

Custom authentication parameters

For JSON-RPC APIs that handle authentication within the request payload:

openrpc.yml

methods:
  - name: auth.login
    summary: Authenticate user
    description: Login method that returns authentication token
    params:
      - name: credentials
        schema:
          type: object
          properties:
            username:
              type: string
            password:
              type: string
          required:
            - username
            - password
    result:
      name: authResult
      schema:
        type: object
        properties:
          token:
            type: string
          expiresIn:
            type: integer
          refreshToken:
            type: string

Fern extensions for authentication

Use Fern extensions to customize authentication behavior:

openrpc.yml

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-fern-token:
        name: authToken
        env: AUTH_TOKEN

This allows users to set authentication via environment variables or constructor parameters, making the SDK more flexible and secure.

Error handling for authentication

Define standardized error responses for authentication failures:

openrpc.yml

components:
  errors:
    - code: -32001
      message: Authentication required
      data:
        type: object
        properties:
          error:
            type: string
            const: "Authentication token is required"
    - code: -32002
      message: Invalid authentication
      data:
        type: object
        properties:
          error:
            type: string
            const: "Invalid or expired authentication token"

These error codes follow JSON-RPC 2.0 conventions while providing clear authentication feedback to API consumers.