API Authentication

Recur uses wallet-based authentication. The subscriber proves wallet ownership by signing a server-generated nonce, then receives a JWT for subsequent API calls.

Flow overview

POST /auth/nonce → { nonce, message }
wallet.signMessage(message) → signature
POST /auth/verify → { token, refreshToken }
Use: Authorization: Bearer <token>
POST /auth/refresh → { token, refreshToken }

`POST /auth/nonce`

Request a nonce for the given wallet.

Request:

{
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

Response (200):

{
  "nonce": "a1b2c3d4e5f6...",
  "message": "Sign this message to authenticate with Recur:\n\nNonce: a1b2c3d4e5f6..."
}

`POST /auth/verify`

Submit the signed message to receive a JWT.

Request:

{
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "message": "Sign this message to authenticate with Recur:\n\nNonce: a1b2c3d4e5f6...",
  "signature": "base64-encoded-signature"
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_abc123..."
}

Error (401):

{
  "error": "Invalid signature"
}

`POST /auth/refresh`

Exchange a refresh token for a new JWT.

Request:

{
  "refreshToken": "rt_abc123..."
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_def456..."
}

Using the JWT

Include the token in the Authorization header for all authenticated endpoints:

const res = await fetch("https://api.recur.so/subscriptions/me", {
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});

Token lifetime

JWT: Short-lived (typically 15 minutes)
Refresh token: Long-lived (typically 7 days)

When the JWT expires, use the refresh endpoint to obtain a new pair without re-signing.

SDK shortcut

The RecurClient.authenticate(wallet) method handles the entire flow in one call:

import { RecurClient } from "@recur/sdk";
 
const recur = new RecurClient({ rpcUrl, apiBaseUrl });
const token = await recur.authenticate(wallet);

API Authentication

On this page