Siva API · v1

API Reference

Everything you need to integrate Siva into your application — authentication, user profiles, wallet balances, and peer-to-peer token transfers.

Bearer Token

Paste your access token once here to auto-fill all authenticated requests in the “Try It” panels below.

Overview

The Siva API is built on NestJS and exposed through a Kong API Gateway. All requests go through the gateway, which enforces JWT authentication, rate limiting, and request routing.

The API uses standard HTTP methods and returns JSON responses. Errors follow the NestJS default format with statusCode, message, and error fields.

Base URL

All API paths are relative to the base URL for your environment. Paths include the /auth prefix from the NestJS global prefix.

Environment	Base URL
Production	`https://api.siva-project.com`
Development (Kong Gateway)	`http://localhost:8000`
Development (Direct Service)	`http://localhost:3001`

The Try It panels send requests to https://api.siva-project.com. The Siva web app is available at act.siva-project.com.

Authentication

Protected endpoints require a JWT Bearer token in the Authorization header. Obtain a token via POST /auth/login or POST /auth/register.

HeaderAuthorization: Bearer <accessToken>

Access token expiry15 minutes

Refresh token expiry7 days

Token rotationRefresh tokens are single-use and rotated on each refresh call

When your access token expires, call POST /auth/refresh with your refresh token to get a new pair without re-authenticating. The JWT payload contains sub (user UUID), email, and role.

Rate Limits

Rate limiting is enforced by the Kong API Gateway using Redis as the backing store. Limits are applied per client IP.

Window	Limit
Per minute	60 requests
Per hour	1,000 requests

When a limit is exceeded, the gateway returns 429 Too Many Requests with a Retry-After header indicating when the window resets.

Quick Start

Get up and running in under a minute. Register a new account, then use your access token to query the API.

bash

# 1. Register and get tokens
curl -X POST https://api.siva-project.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"password123"}'

# Response → { "accessToken": "eyJ...", "refreshToken": "a1b2..." }

# 2. Use the access token to check your balance
curl https://api.siva-project.com/auth/balance \
  -H "Authorization: Bearer eyJ..."

# Response → { "balance": 0 }

# 3. Refresh an expiring access token
curl -X POST https://api.siva-project.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"a1b2..."}'

Authentication

POST/auth/registerRegister

Create a new Siva account with email and password. Returns a short-lived access token (15 min) and a long-lived refresh token (7 days).

Request Body

Field	Type	Required	Description
`email`	string	required	A valid email address.
`password`	string	required	Minimum 8 characters.
`firstName`	string	optional	Optional first name.
`lastName`	string	optional	Optional last name.

Sample Request

json

{
  "email": "john@example.com",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe"
}

Responses

User registered successfully.

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJyb2xlIjoidXNlciIsImlhdCI6MTcxNjIxMTQwMCwiZXhwIjoxNzE2MjEyMzAwfQ.signature",
  "refreshToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

POST/auth/loginLogin

Authenticate with email and password. Returns a new access token and refresh token pair.

Request Body

Field	Type	Required	Description
`email`	string	required	Your registered email address.
`password`	string	required	Your account password.

Sample Request

json

{
  "email": "john@example.com",
  "password": "password123"
}

Responses

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature",
  "refreshToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

POST/auth/refreshRefresh Token

Exchange a valid refresh token for a new access/refresh token pair. The old refresh token is immediately revoked (token rotation).

Request Body

Field	Type	Required	Description
`refreshToken`	string	required	A valid refresh token from a prior login or register call.

Sample Request

json

{
  "refreshToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Responses

Token refreshed successfully.

json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.newpayload.newsignature",
  "refreshToken": "z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0"
}

POST/auth/logoutLogout🔒

Revoke a refresh token, ending the associated session. The access token remains valid until it naturally expires.

Request Body

Field	Type	Required	Description
`refreshToken`	string	required	The refresh token to revoke.

Sample Request

json

{
  "refreshToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Responses

Logged out successfully. No response body.

No response body.

GET/auth/oauth/googleGoogle OAuth

Initiate Google OAuth 2.0 sign-in. Opens the Google consent screen. After approval, the user is redirected to your frontend with tokens in the query string: `?accessToken=...&refreshToken=...`

Responses

Redirect to Google consent screen.

No response body.

GET/auth/oauth/linkedinLinkedIn OAuth

Initiate LinkedIn OAuth 2.0 sign-in. Opens the LinkedIn consent screen. After approval, the user is redirected to your frontend with tokens.

Responses

Redirect to LinkedIn consent screen.

No response body.

User

GET/auth/meGet Current User🔒

Returns the full profile of the currently authenticated user, including their Siva balance.

Responses

User profile retrieved.

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "oauthProvider": null,
  "oauthProviderId": null,
  "emailVerified": true,
  "role": "user",
  "sivaBalance": 1000,
  "createdAt": "2024-05-20T10:30:00.000Z",
  "updatedAt": "2024-05-20T10:30:00.000Z"
}

Wallet

GET/auth/balanceGet Balance🔒

Returns the current Siva token balance of the authenticated user.

Responses

Balance retrieved.

json

{
  "balance": 1000
}

GET/auth/transactionsGet Transactions🔒

Returns the last 50 transactions where the user is sender or recipient, ordered by most recent first.

Responses

Transaction history returned.

json

[
  {
    "id": "650e8400-e29b-41d4-a716-446655440001",
    "senderId": "550e8400-e29b-41d4-a716-446655440000",
    "recipientId": "550e8400-e29b-41d4-a716-446655440002",
    "senderEmail": "john@example.com",
    "recipientEmail": "jane@example.com",
    "amount": 100,
    "type": "transfer",
    "txHash": "0x1234567890abcdef1234567890abcdef12345678",
    "chainStatus": "confirmed",
    "createdAt": "2024-05-20T11:45:00.000Z"
  }
]

POST/auth/transferTransfer Siva🔒

Transfer Siva tokens to another user by their email. The operation is atomic — sender's balance is debited and recipient's balance is credited in a single database transaction. Transfers are optionally logged to the BNB testnet as an audit trail.

Request Body

Field	Type	Required	Description
`recipientEmail`	string	required	Email address of the recipient (must have a Siva account).
`amount`	number	required	Positive integer amount. Must not exceed your current balance.

Sample Request

json

{
  "recipientEmail": "jane@example.com",
  "amount": 100
}

Responses

Transfer successful.

json

{
  "senderBalance": 900,
  "recipientEmail": "jane@example.com"
}

The Siva API is actively developed. Endpoints, schemas, and base URLs will be updated as new services launch.