Authentication

StepFi uses Stellar wallet signatures for authentication. No passwords, no email, no KYC.

Flow

• Request a nonce

  POST /api/v1/auth/nonce
  Content-Type: application/json
  
  {
    "walletAddress": "GCBMQ7YH2XPNM4KLWRS9JF3EVKD5A8T4X7F"
  }
  

  Response:

  {
    "nonce": "stepfi_auth_a3f8b2c1d4e5",
    "expiresAt": "2026-05-14T15:30:00Z"
  }
  

• Sign the nonce

  Sign the nonce string with your Stellar wallet using Freighter or Lobstr.

• Verify the signature

  POST /api/v1/auth/verify
  Content-Type: application/json
  
  {
    "walletAddress": "GCBMQ7YH...",
    "signature": "signed_nonce_here",
    "nonce": "stepfi_auth_a3f8b2c1d4e5"
  }
  

  Response:

  {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "expiresIn": 3600
  }
  

• Use the access token

  Include the token in all subsequent requests:

  Authorization: Bearer eyJhbGc...
  

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new pair:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGc..."
}