Katixo/API DocumentationBeta

Authentication

The Katixo API uses JWT (JSON Web Token) Bearer tokens for authentication. Tokens are obtained by signing in with OTP or password, and include the user's role and organization context.

Auth endpoints

POST/api/v1/auth/otp/request

POST/api/v1/auth/otp/verify

POST/api/v1/auth/signup

POST/api/v1/auth/register

POST/api/v1/auth/login

POST/api/v1/auth/refresh

POST/api/v1/auth/logout

GET/api/v1/auth/me

POST/api/v1/auth/forgot-password

POST/api/v1/auth/reset-password

POST/api/v1/auth/invite

POST/api/v1/auth/invite/accept

Authentication flow

There are two ways to authenticate: OTP-based signup/login and password-based login.

1. OTP-based signup

Request an OTP, verify it, then complete registration:

# Step 1: Request OTP
curl -X POST https://api.katixo.com/api/v1/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210" }'

# Step 2: Verify OTP
curl -X POST https://api.katixo.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210", "otp": "123456" }'

# Step 3: Complete signup with organization details
curl -X POST https://api.katixo.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "name": "Rajesh Kumar",
    "email": "[email protected]",
    "password": "secureP@ss123",
    "businessName": "Kumar General Store",
    "businessType": "RETAILER"
  }'

2. Password login

For existing users with a password set:

curl -X POST https://api.katixo.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "password": "secureP@ss123"
  }'

Both flows return an AuthResponse:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Rajesh Kumar",
      "phone": "+919876543210",
      "email": "[email protected]",
      "role": "OWNER"
    }
  },
  "errors": null
}

Making authenticated requests

Include the access token in the Authorization header as a Bearer token:

curl https://api.katixo.com/api/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token without re-authenticating:

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

Returns a new accessToken and refreshToken pair.

Roles & permissions

Each user is assigned a role within their organization. The role determines which API endpoints they can access:

Role	Permissions
`OWNER`	Full access. Can manage organization settings, users, and all data.
`ADMIN`	Full access to data. Can invite users and manage settings.
`ACCOUNTANT`	Read/write for invoices, purchases, expenses, GST, contacts, items. Can approve workflows.
`OPERATOR`	Read/write for invoices, items, contacts, inventory. Cannot access GST reports or approve workflows.
`VIEWER`	Read-only access to all data. Cannot create, update, or delete.

Multi-organization

A user can belong to multiple organizations (e.g., a CA firm managing several clients). The JWT token contains the active org_id claim. To switch organizations:

# List your organizations
curl https://api.katixo.com/api/v1/users/me/organisations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Switch to a different org (returns new tokens)
curl -X POST https://api.katixo.com/api/v1/users/me/switch-org \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "b7d2f8a0-1234-4567-89ab-cdef01234567" }'

Invite team members

Organization owners and admins can invite users via phone number:

curl -X POST https://api.katixo.com/api/v1/auth/invite \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543211",
    "role": "ACCOUNTANT",
    "name": "Priya Sharma"
  }'

The invited user receives an SMS with a link to accept the invitation and set up their account.

Security: Never expose JWT tokens in client-side code or public repositories. Store tokens securely and use HTTPS for all requests. If a token is compromised, use the logout endpoint to invalidate all active sessions.

Password recovery

Users can reset their password via OTP-verified flow:

# Request password reset OTP
curl -X POST https://api.katixo.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210" }'

# Reset password with OTP
curl -X POST https://api.katixo.com/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "otp": "123456",
    "newPassword": "newSecureP@ss456"
  }'