Reference
Auth & Pairing
Authentication, profile, and mobile-device pairing endpoints.
Endpoint Map
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/v1/auth/login | None | Verify email/password and issue login JWT |
POST | /api/v1/auth/verify-credentials | None | Verify email/password without issuing JWT |
GET | /api/v1/auth/me | JWT | Get current user profile |
PUT | /api/v1/auth/me | JWT | Update current user profile |
POST | /api/v1/auth/change-password | JWT | Change current user password |
POST | /api/v1/auth/pairing-code | Flexible auth | Create short-lived pairing token + deep link |
GET | /api/v1/auth/pair-link/:code | None | Render HTML redirect page for app pairing |
POST | /api/v1/auth/pair | Pairing token | Exchange pairing token for long-lived device JWT |
Login
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "admin@example.com",
"password": "secret"
}{
"success": true,
"token": "<jwt>",
"user": {
"id": "usr_...",
"email": "admin@example.com",
"name": "Admin",
"tenantId": "tnt_...",
"roles": ["admin"]
}
}Verify Credentials (No JWT)
POST /api/v1/auth/verify-credentials
Content-Type: application/json
{
"email": "admin@example.com",
"password": "secret"
}Used by management apps that mint JWTs themselves.
Current Profile
GET /api/v1/auth/me
Authorization: Bearer <jwt>Update Profile
PUT /api/v1/auth/me
Authorization: Bearer <jwt>
Content-Type: application/json
{
"name": "Updated Name",
"email": "new@example.com"
}Change Password
POST /api/v1/auth/change-password
Authorization: Bearer <jwt>
Content-Type: application/json
{
"currentPassword": "old-pass",
"newPassword": "new-pass-123"
}Device Pairing Flow
- Runtime calls
POST /api/v1/auth/pairing-codewith flexible auth andpeerId. - Gateway returns
{ token, deepLink }. - Mobile app opens
deepLinkand then callsPOST /api/v1/auth/pairwith:
{
"pairingToken": "...",
"pushToken": "...",
"platform": "ios",
"deviceName": "iPhone 16"
}/pair response:
{
"token": "<device-jwt>",
"gatewayUrl": "https://...",
"peerId": "usr_..."
}