v1 Stable

API Documentation

Everything you need to integrate with the HelloSIM API

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

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":"your-password"}' \

-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