Quick Start

Get up and running with the Keshless API.

API Endpoints

Environment	Base URL
Production	https://api.keshless.app
Development	https://dev-api.keshless.app

Authentication

Keshless uses JWT-based authentication with OTP verification.

1. Register a User

curl -X POST https://dev-api.keshless.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+26878123456",
    "password": "SecureP@ss123",
    "firstName": "John",
    "lastName": "Doe"
  }'

Response:

{
  "success": true,
  "message": "Registration successful. OTP sent to your phone.",
  "data": {
    "userId": "usr_abc123...",
    "requiresOTP": true
  }
}

2. Verify OTP

curl -X POST https://dev-api.keshless.app/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+26878123456",
    "otp": "123456",
    "purpose": "REGISTRATION"
  }'

3. Login

curl -X POST https://dev-api.keshless.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+26878123456",
    "password": "SecureP@ss123"
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "usr_abc123...",
      "phoneNumber": "+26878123456",
      "firstName": "John",
      "lastName": "Doe",
      "kycStatus": "PENDING",
      "walletBalance": 0
    }
  }
}

4. Use the Token

Include the access token in all subsequent requests:

curl -X GET https://dev-api.keshless.app/api/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

---

Token Lifecycle

Token	Expiry	Purpose
Access Token	7 days	API authentication
Refresh Token	30 days	Get new access token

Refresh Token

curl -X POST https://dev-api.keshless.app/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

---

KYC Verification

Users must complete KYC before making transactions.

1. Upload ID Documents

curl -X POST https://dev-api.keshless.app/api/kyc/upload \
  -H "Authorization: Bearer <token>" \
  -F "idFront=@/path/to/id-front.jpg" \
  -F "idBack=@/path/to/id-back.jpg" \
  -F "selfie=@/path/to/selfie.jpg"

2. Check KYC Status

curl -X GET https://dev-api.keshless.app/api/kyc/status \
  -H "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "data": {
    "status": "IN_PROGRESS",
    "documents": {
      "idFront": "uploaded",
      "idBack": "uploaded",
      "selfie": "uploaded"
    },
    "ocrResult": {
      "names": "JOHN",
      "surname": "DOE",
      "dateOfBirth": "1990-01-15",
      "personalIdNumber": "1234567890123"
    }
  }
}

---

Basic Transactions

Check Balance

curl -X GET https://dev-api.keshless.app/api/wallet/balance \
  -H "Authorization: Bearer <token>"

P2P Transfer

curl -X POST https://dev-api.keshless.app/api/transactions/p2p \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientPhone": "+26878987654",
    "amount": 100,
    "pin": "1234",
    "description": "Lunch money"
  }'

Transaction History

curl -X GET "https://dev-api.keshless.app/api/transactions?limit=10" \
  -H "Authorization: Bearer <token>"

---

Error Handling

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Invalid credentials"
  }
}

Common Error Codes

Code	Status	Description
AUTH_REQUIRED	401	Missing or invalid token
AUTH_FAILED	401	Invalid credentials
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request data
KYC_REQUIRED	403	KYC not completed
INSUFFICIENT_BALANCE	400	Not enough funds
RATE_LIMITED	429	Too many requests

---

Rate Limits

Endpoint Category	Limit	Window
Authentication	10 requests	15 minutes
OTP Requests	5 requests	15 minutes
General API	100 requests	15 minutes
Transactions	50 requests	15 minutes

---

SDKs & Libraries

JavaScript/TypeScript

import { KeshlessClient } from '@keshless/sdk';

const client = new KeshlessClient({
  baseUrl: 'https://dev-api.keshless.app',
  accessToken: 'your-token'
});

// Get user profile
const user = await client.users.me();

// Make a transfer
const transfer = await client.transactions.p2p({
  recipientPhone: '+26878987654',
  amount: 100,
  pin: '1234'
});

Flutter/Dart

import 'package:keshless_sdk/keshless_sdk.dart';

final client = KeshlessClient(
  baseUrl: 'https://dev-api.keshless.app',
  accessToken: 'your-token',
);

// Get balance
final balance = await client.wallet.getBalance();

---

Next Steps

• Architecture - System overview
• Integration Guide - Vendor integration
• API Reference - Full API documentation
• KYC Workflow - KYC details