Skip to content

Authentication (Login)

Authentication endpoints issue access and refresh tokens for users authenticating with externally owned wallets. Wallet creation and custody remain entirely under your control.

Wallet Signature Login

When should I use this?

  • Use when users own a wallet and prefer signing challenges instead of creating credentials. Wallets are fully provisioned and controlled externally by you or your users; PAYCIFI does not manage wallet creation in this flow.
  • Required for wallets that skipped the email/password signup path. This endpoint authenticates wallet owners. If the wallet address is not yet known, PAYCIFI automatically creates a new user record associated with that wallet during authentication.

Purpose

Authenticate owned-wallet users via nonce signing without using email/password credentials.

Preconditions

  • Client ensures a supported wallet extension/app is installed and connected.
  • Wallet creation happens outside PAYCIFI; only wallets you already manage can authenticate here.
  • This flow is intended exclusively for owned wallets and cannot be used to authenticate PAYCIFI-managed delegate wallets.
  • Client can display wallet modal interactions and capture signatures.

Client Responsibilities

  • MUST verify that the wallet provider is installed and connected before requesting the nonce.
  • MUST present the nonce to the user for signing and capture the signature output.
  • SHOULD disconnect the wallet if the verification response lacks tokens.

API Flow

  1. Client checks wallet availability. If absent, abort and display no-wallet.
  2. Client ensures the wallet is connected; otherwise, trigger wallet connection. Abort on connection failure with wallet-connection-error.
  3. Client calls GET /auth/nonce to retrieve { nonce, backSig }.
  4. User signs the nonce via the wallet. Abort on signature errors.
  5. Client submits POST /auth/nonce with { userAddress, frontSig, nonce, backSig }.
  6. Backend validates payload integrity, links or creates the user, generates JWTs, stores refresh token, and returns { user, accessToken, refreshToken }.

Example request

POST /auth/nonce
Content-Type: application/json

{
  "userAddress": "0x92c5...bc10",
  "frontSig": "0x7c9c5b...",
  "nonce": "Please connect your wallet by signing the following message:\nnonce:5a84c3e98d9c",
  "backSig": "f8f1337dc5b5d5703f7d7a8b9814d9ebfca4d0f7f2bb1d3a39c2b1c4ab3d8e90"
}

Example response

{
  "user": {
    "userId": "6ce832d9-64a8-40f7-a8c9-61f8d7d00101",
    "walletAddress": "0x92c5...bc10",
    "walletType": "owned_wallet",
    "firstname": "Lena",
    "lastname": "Signer",
    "accountType": "standard"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Handling

  • Success: persist tokens and user data, then proceed with any post-login flows.
  • Failure: inspect errorCode to guide user messaging (e.g., wallet missing, signature failure). Disconnect wallet if instructed.

Error Codes

  • no-wallet – wallet provider not detected.
  • wallet-connection-error – wallet could not connect or disconnected mid-flow.
  • signature-error / invalid-signature – user declined or wallet returned invalid signature.
  • missing-data – nonce verification payload incomplete.
  • invalid-nonce – integrity check failed for nonce/backSig.
  • user-check-error, user-creation-error, refresh-token-update-error – backend persistence issues.
  • GET /auth/nonce
  • POST /auth/nonce

Note: Email/password authentication exists only for PAYCIFI-managed delegate wallets and is not available to external integrators.