API Reference

API Reference

Overview

SIGNula provides a RESTful JSON API for authentication, user management, and partner integration. The API lives at https://api.signula.id/v1/.

Authentication Methods

API Keys (Partner Access)

Partners authenticate with API keys passed in the X-API-Key header:

X-API-Key: sk_live_abc123def456...

API keys are managed in the Partner Dashboard under API Keys. Each key has:

• Prefix: sk_live_ (production) or sk_test_ (sandbox)
• Permissions: Configurable per-endpoint access
• Rate limits: Per-key rate limit configuration

JWT Tokens (User Sessions)

After successful login, the API returns a JWT token for subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens contain:

• sub: User ID
• iat: Issued at timestamp
• exp: Expiration timestamp
• scope: Permission scope

Endpoints

Authentication

Method	Endpoint	Description
POST	/v1/auth/login	Authenticate with email/password
POST	/v1/auth/register	Create a new account
POST	/v1/auth/logout	Invalidate current session
POST	/v1/auth/mfa/verify	Submit MFA verification code
POST	/v1/auth/passwordless/request	Request passwordless login link
POST	/v1/auth/passwordless/verify	Verify passwordless token
POST	/v1/auth/password/reset	Request password reset
POST	/v1/auth/password/update	Set new password with reset token

User Management

Method	Endpoint	Description
GET	/v1/user/profile	Get current user profile
PUT	/v1/user/profile	Update profile information
GET	/v1/user/avatar/{uuid}/{size}	Get user avatar
POST	/v1/user/avatar/upload	Upload avatar image
GET	/v1/user/activity	Get activity log
GET	/v1/user/sessions	List active sessions
DELETE	/v1/user/sessions/{id}	Revoke a session

MFA Management

Method	Endpoint	Description
POST	/v1/mfa/totp/setup	Generate TOTP secret and QR URI
POST	/v1/mfa/totp/activate	Activate TOTP with verification code
DELETE	/v1/mfa/totp	Disable TOTP
POST	/v1/mfa/backup-codes/generate	Generate new backup codes
GET	/v1/mfa/status	Get MFA status for current user

OAuth

Method	Endpoint	Description
GET	/v1/oauth/{provider}/redirect	Get OAuth redirect URL
POST	/v1/oauth/{provider}/callback	Handle OAuth callback
GET	/v1/oauth/accounts	List linked OAuth accounts
DELETE	/v1/oauth/accounts/{id}	Unlink an OAuth account

Partner API

Method	Endpoint	Description
GET	/v1/partner/info	Get partner organisation info
GET	/v1/partner/users	List partner's users
POST	/v1/partner/users/verify	Verify a user's identity
GET	/v1/partner/webhooks	List webhook endpoints
POST	/v1/partner/webhooks	Register a webhook endpoint

Request Format

All POST/PUT requests must use Content-Type: application/json:

{
    "email": "user@example.com",
    "password": "SecurePassword123!"
}

Response Format

All responses follow a consistent structure:

Success Response

{
    "success": true,
    "message": "Login successful",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "user": {
            "userID": 42,
            "email": "user@example.com",
            "displayName": "John Doe"
        }
    }
}

Error Response

{
    "success": false,
    "message": "Invalid credentials",
    "errors": [
        {
            "field": "password",
            "message": "The password is incorrect"
        }
    ]
}

MFA Challenge Response

{
    "success": true,
    "message": "MFA verification required",
    "data": {
        "mfa_required": true,
        "mfa_token": "temporary_mfa_session_token",
        "mfa_methods": ["totp", "backup_code"]
    }
}

Rate Limiting

Rate limits are applied per-endpoint and tracked by API key or IP address:

Endpoint	Limit	Window
/auth/login	5 requests	15 minutes
/auth/register	3 requests	1 hour
/auth/password/reset	3 requests	1 hour
General API	60 requests	1 minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1708891200
Retry-After: 45

HTTP Status Codes

Code	Meaning
200	Success
201	Created (new resource)
400	Bad request (validation error)
401	Unauthorized (missing/invalid token)
403	Forbidden (insufficient permissions)
404	Not found
415	Unsupported Media Type (wrong Content-Type)
429	Rate limit exceeded
500	Internal server error

Webhook Events

Partners can subscribe to these webhook events:

Event	Description
user.created	New user registered via partner
user.updated	User profile updated
user.deleted	User account deleted
subscription.created	New subscription started
subscription.cancelled	Subscription cancelled
payment.completed	Payment processed successfully
payment.failed	Payment processing failed
security.alert	Security event triggered

Webhooks are signed with HMAC-SHA256. Verify the X-Signature-256 header:

$signature = hash_hmac('sha256', $payload, $webhookSecret);
$isValid = hash_equals($signature, $receivedSignature);