Authentication

Overview

The EmaalCoin API uses PASETO bearer tokens for authentication. Obtain tokens via login endpoints and send them in the Authorization header.

Token Types

Token	Lifetime	Purpose
Access Token	~15 minutes	Authenticate API requests
Refresh Token	Long-lived	Obtain new access tokens

Email + Password

POST /api/v1/users/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Returns access_token and refresh_token (PASETO).

POST /api/v1/users/login-pin
Content-Type: application/json

{
  "email": "user@example.com",
  "pin": "123456"
}

Or with phone number:

{
  "phone_number": "+254712345678",
  "pin": "123456"
}

Refresh Token Flow

When the access token expires, exchange the refresh token for new tokens:

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

{
  "refresh_token": "<your_refresh_token>"
}

Refresh token rotation is enabled. The old refresh token is revoked immediately after use. Always use the new refresh token returned in the response for future refreshes.

Using the Token

Add the access token to every protected request:

Authorization: Bearer v2.local.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

PIN Management

Set during registration: Include pin in POST /api/v1/users/register
Update existing PIN: PUT /api/v1/auth/user/id/{id}/pin

Unauthenticated Endpoints

These endpoints do not require a token:

POST /api/v1/users/register
POST /api/v1/users/login-pin

Getting Started

Guides

Overview

Token Types

Email + Password

Refresh Token Flow

Using the Token

PIN Management

Unauthenticated Endpoints

​Overview

​Token Types

​Login Endpoints

​Email + Password

​PIN Login

​Refresh Token Flow

​Using the Token

​PIN Management

​Unauthenticated Endpoints

Overview

Token Types

Login Endpoints

Email + Password

PIN Login

Refresh Token Flow

Using the Token

PIN Management

Unauthenticated Endpoints