API Documentation

Everything you need to integrate with the HelloSIM API

Base URL:https://api.hellosim.net/api/v1

v1 Stable

Endpoints

Guides

Quick Start Auth Flow Error Handling Rate Limits

Quick Start

The HelloSIM API uses REST over HTTPS. All requests must include a Content-Type: application/json header. Authentication uses httpOnly JWT cookies — tokens are set automatically on login.

# Login to get JWT cookies

curl -X POST https://api.hellosim.net/api/v1/auth/login \

-H "Content-Type: application/json" \

-d '{"email":"[email protected]","password":"User123!"}' \

-c cookies.txt

# Use cookies for authenticated requests

curl https://api.hellosim.net/api/v1/esims/me -b cookies.txt

Authentication

POST/auth/register

Create a new user account

Request Body:

{ email, password, firstName, lastName }

POST/auth/login

Request Body:

{ email, password }

POST/auth/refresh

Refresh access token using refresh token

Request Body:

{}

POST/auth/logout

Logout and invalidate tokens

Request Body:

{}

GET/auth/me

Get current user profile

POST/auth/forgot-password

Request a password reset email

Request Body:

{ email }

POST/auth/reset-password

Reset password with token

Request Body:

{ token, newPassword }

Authentication Flow

Register or Login — POST to /auth/register or /auth/login. Tokens are set as httpOnly cookies automatically.

Make Requests — Include cookies with every request. Access token expires in 15 minutes.

Auto-Refresh — When access token expires, POST to /auth/refresh with the refresh cookie. New tokens are returned.

Logout — POST to /auth/logout to clear all tokens.

Error Handling

All errors follow a consistent format:

{ "success": false, "error": { "statusCode": 400, "message": "Validation failed" } }

Code	Meaning
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Rate Limits

General: 60 requests per minute per IP

Auth endpoints: 5 requests per minute (login, register, forgot-password)

Password reset: 3 requests per minute

Exceeding limits returns 429 Too Many Requests. Implement exponential backoff in your integration.

Deployment & Setup Guide

Prerequisites

Node.js 18+ and pnpm
PostgreSQL 14+
Redis (optional — for queues and caching)
Stripe account for payments
HelloSIM API credentials

1. Clone & Install

git clone https://github.com/hellosim/hellosim.git

cd hellosim

pnpm install

2. Environment Setup

Copy .env.example to .env and configure:

# Database

DATABASE_URL=postgresql://user:pass@localhost:5432/hellosim

# JWT (generate random 64-char strings)

JWT_SECRET=your-jwt-secret

REFRESH_SECRET=your-refresh-secret

# Stripe

STRIPE_SECRET_KEY=sk_live_xxx

# HelloSIM API

HELLOSIM_API_URL=https://api.hellosim.net

HELLOSIM_API_TOKEN=your-token

# Frontend

NEXT_PUBLIC_API_URL=https://api.hellosim.net/api/v1

3. Database Setup

# Create database and run migrations

createdb hellosim

pnpm db:migrate

pnpm db:generate

# Seed with test data

pnpm db:seed

4. Run Development

# Start both API and web

pnpm dev

# Or separately:

pnpm dev:api # Port 3001

pnpm dev:web # Port 3000

5. Production Deploy

# Build for production

pnpm build

# API: Deploy apps/api (NestJS)

# Web: Deploy apps/web (Next.js) to Vercel

# Domain: hellosim.net

Project Structure

hellosim/

apps/

api/ # NestJS backend (port 3001)

src/

auth/ # JWT auth, guards, strategies

esims/ # eSIM management

orders/ # Order processing

hellosim-api/ # 57 API methods

admin/ # Admin endpoints

prisma/ # Schema + migrations

web/ # Next.js frontend (port 3000)

src/

app/ # Pages (i18n routing)

components/ # Reusable components

lib/ # API client, utilities

data/ # Demo/seed data