Rails Auth API — Rails Cloud

← All APIs · Pay Media Vault Messaging Location

Base URL

            https://auth.railscloud.co/api/v1
        

Authentication

Include your API key in the Authorization header. Public endpoints (OTP request, login) don't require a user token. Protected endpoints require both your API key and a user session token.

# API key authentication (all requests)
Authorization: Bearer dk_live_your_api_key

# User session (protected endpoints)
X-Session-Token: usr_session_token_here

How Authentication Works

Rails Auth uses an OTP-first flow. Your app requests an OTP for the user's phone number, the user enters the code, and you verify it to get session tokens.

1 Your app calls POST /auth/otp/request with the user's phone number

2 User receives an SMS with a 6-digit code

3 Your app calls POST /auth/otp/verify with the code to get tokens

4 Use the session token on all subsequent authenticated requests

Quick Start

# Step 1: Request an OTP
curl -X POST https://auth.railscloud.co/api/v1/auth/otp/request \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+263771234567"}'

# Response: {"data": {"message": "OTP sent", "expires_in": 300}}

# Step 2: Verify the OTP
curl -X POST https://auth.railscloud.co/api/v1/auth/otp/verify \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+263771234567", "code": "123456"}'

# Response: {"data": {"access_token": "...", "refresh_token": "...", "user": {...}}}

# Step 3: Use the token for authenticated requests
curl https://auth.railscloud.co/api/v1/users/me \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN_FROM_STEP_2"

Endpoints

Authentication

POST /auth/otp/request Send OTP to phone number

POST /auth/otp/verify Verify OTP and get tokens

POST /auth/register Register a new user

POST /auth/login Login with credentials

POST /auth/login/totp Complete login with 2FA code

POST /auth/refresh Refresh an expired access token

POST /auth/logout Invalidate the current session

User Profile

GET /users/me Get current user profile

PATCH /users/me Update user profile

POST /users/me/avatar Upload user avatar

GET /users/lookup Look up user by phone number

DELETE /users/me Delete user account

POST /users/me/pin Set a transaction PIN

POST /users/me/pin/verify Verify PIN before sensitive actions

KYC Verification

GET /users/me/kyc Get KYC verification status

POST /users/me/kyc/submit Submit identity documents for KYC

GET /users/me/kyc/{id} Get specific verification details

Sessions

GET /users/me/sessions List all active sessions

DELETE /users/me/sessions/{id} Revoke a specific session

POST /users/me/security/sessions/revoke-all Revoke all sessions (force logout everywhere)

Two-Factor Authentication (TOTP)

POST /users/me/security/2fa/setup Generate TOTP secret and QR code

POST /users/me/security/2fa/enable Confirm and enable 2FA

POST /users/me/security/2fa/verify Verify a TOTP code

POST /users/me/security/2fa/disable Disable 2FA for the user

POST /users/me/security/2fa/backup-codes/regenerate Generate new backup codes

Password

GET /users/me/security Get security summary (2FA status, password set, etc.)

POST /users/me/security/password Set initial password

PUT /users/me/security/password Change existing password

Devices

GET /users/me/devices List registered devices

DELETE /users/me/devices/{id} Remove a device

POST /users/me/devices/{id}/trust Mark a device as trusted

Contacts & Recipients

GET /recipients List saved recipients

POST /recipients Create a recipient

GET /recipients/search Search recipients

GET /recipients/{id} Get recipient details

DELETE /recipients/{id} Delete a recipient

Example: Register a User

curl -X POST https://auth.railscloud.co/api/v1/auth/register \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+263771234567",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  }'

Returns the created user object with a session token. The user will receive an OTP to verify their phone number.

Example: Enable Two-Factor Authentication

# Step 1: Get the TOTP secret and QR URI
curl -X POST https://auth.railscloud.co/api/v1/users/me/security/2fa/setup \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN"

# Response: {"data": {"secret": "JBSWY3DPEHPK3PXP", "qr_uri": "otpauth://..."}}

# Step 2: User scans QR in their authenticator app, then confirm
curl -X POST https://auth.railscloud.co/api/v1/users/me/security/2fa/enable \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# Response: {"data": {"enabled": true, "backup_codes": ["abc123", ...]}}

Rate Limits

OTP requests 5 per phone per 15 minutes

General API calls Based on your tier (600–1,000 req/min)

Error Responses

All errors follow a standard format.

{
  "error": "invalid_otp",
  "message": "The OTP code is invalid or expired"
}

401 Invalid or missing API key / session token

403 Action not permitted (e.g., KYC required)

404 User or resource not found

422 Validation error (check field-level errors)

429 Rate limit exceeded

Get Started with Rails Auth