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

1 servers:
2   - name: production
3     url: https://api.example.com/rpc
4     description: Production JSON-RPC server
5     security:
6       - bearerAuth: []
7 components:
8   securitySchemes:
9     bearerAuth:
10       type: http
11       scheme: bearer
12       bearerFormat: JWT

This generates SDK methods that require a token:

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

API Key Authentication

Configure API key authentication:

openrpc.yml

1 servers:
2   - name: production
3     url: https://api.example.com/rpc
4     description: Production JSON-RPC server
5     security:
6       - apiKeyAuth: []
7 components:
8   securitySchemes:
9     apiKeyAuth:
10       type: apiKey
11       in: header
12       name: X-API-Key

Usage in SDK:

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

Basic Authentication

Configure basic authentication:

openrpc.yml

1 servers:
2   - name: production
3     url: https://api.example.com/rpc
4     description: Production JSON-RPC server
5     security:
6       - basicAuth: []
7 components:
8   securitySchemes:
9     basicAuth:
10       type: http
11       scheme: basic

Usage in SDK:

1 const client = new JSONRPCClient({
2   url: "https://api.example.com/rpc",
3   auth: {
4     username: "user@example.com",
5     password: "password123"
6   }
7 });

Method-Level Authentication

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

openrpc.yml

1 methods:
2   - name: public.getInfo
3     summary: Get public information
4     description: Publicly accessible method (no auth required)
5     params: []
6     result:
7       name: info
8       schema:
9         type: object
10   - name: user.getProfile
11     summary: Get user profile
12     description: Requires user authentication
13     security:
14       - bearerAuth: []
15     params:
16       - name: userId
17         schema:
18           type: string
19         required: true
20     result:
21       name: profile
22       schema:
23         $ref: '#/components/schemas/UserProfile'

WebSocket Authentication

For WebSocket transport, authentication typically happens during connection establishment:

openrpc.yml

1 servers:
2   - name: websocket
3     url: wss://api.example.com/rpc
4     description: WebSocket JSON-RPC server
5     variables:
6       token:
7         description: Authentication token for WebSocket connection
8         default: ""
9     security:
10       - wsAuth: []
11 components:
12   securitySchemes:
13     wsAuth:
14       type: apiKey
15       in: query
16       name: token
17       description: Authentication token passed as query parameter

Custom Authentication Parameters

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

openrpc.yml

1 methods:
2   - name: auth.login
3     summary: Authenticate user
4     description: Login method that returns authentication token
5     params:
6       - name: credentials
7         schema:
8           type: object
9           properties:
10             username:
11               type: string
12             password:
13               type: string
14           required:
15             - username
16             - password
17     result:
18       name: authResult
19       schema:
20         type: object
21         properties:
22           token:
23             type: string
24           expiresIn:
25             type: integer
26           refreshToken:
27             type: string

Fern Extensions for Authentication

Use Fern extensions to customize authentication behavior:

openrpc.yml

1 components:
2   securitySchemes:
3     bearerAuth:
4       type: http
5       scheme: bearer
6       x-fern-token:
7         name: authToken
8         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

1 components:
2   errors:
3     - code: -32001
4       message: Authentication required
5       data:
6         type: object
7         properties:
8           error:
9             type: string
10             const: "Authentication token is required"
11     - code: -32002
12       message: Invalid authentication
13       data:
14         type: object
15         properties:
16           error:
17             type: string
18             const: "Invalid or expired authentication token"

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