Authentication & Permissions

All API requests require authentication. Transportial uses JWT bearer tokens with role-based access control. This guide covers login, session management, two-factor authentication, and permissions.

Authenticate with your username and password to receive a bearer token:

curl -X POST https://api.otms.transportial.com/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "password": "your-password"
  }'

Response:

{
  "success": true,
  "message": "OK",
  "session": {
    "id": "session-uuid",
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "refresh-token-uuid",
    "expiresAt": "2026-03-23T12:00:00Z",
    "permissions": [
      { "name": "create:transportOrder" },
      { "name": "get:transportOrders" }
    ]
  }
}

Use the access_token in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

For accounts with OTP (one-time password) enabled:

curl -X POST https://api.otms.transportial.com/api/user/login:otp \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "otp": "123456"
  }'

Registration

Portal Registration

Standard: portal.otms.transportial.com/auth/register
Developer: portal.otms.transportial.com/auth/developer/register

API Registration

curl -X POST https://api.otms.transportial.com/api/user/register \
  -H "Content-Type: application/json" \
  -d '{
    "type": "USER",
    "accountType": "PLANNING",
    "firstName": "Jane",
    "lastName": "Doe",
    "username": "jane@acme-logistics.com",
    "email": "jane@acme-logistics.com",
    "password": "secure-password",
    "repeatPassword": "secure-password",
    "termsAndConditions": true
  }'

This creates your user, platform, and initial configuration.

Two-Factor Authentication (2FA)

Setup 2FA

curl -X POST https://api.otms.transportial.com/api/user/2fa/setup \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns a QR code or secret key for your authenticator app.

Verify 2FA

curl -X POST https://api.otms.transportial.com/api/user/2fa/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "code": "123456"
  }'

Disable 2FA

curl -X POST https://api.otms.transportial.com/api/user/2fa/disable \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "code": "123456"
  }'

Recover 2FA

If you lose access to your authenticator:

curl -X POST https://api.otms.transportial.com/api/user/2fa/recover \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "recoveryCode": "your-recovery-code"
  }'

Session Management

Get Current Session

curl -X GET https://api.otms.transportial.com/api/user/session \
  -H "Authorization: Bearer YOUR_TOKEN"

List All Sessions

curl -X GET https://api.otms.transportial.com/api/user/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

Logout

# Logout current session
curl -X GET https://api.otms.transportial.com/api/user/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

# Logout all sessions
curl -X GET https://api.otms.transportial.com/api/user/logout/all \
  -H "Authorization: Bearer YOUR_TOKEN"

Password Management

Change Password

curl -X PUT https://api.otms.transportial.com/api/user/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "currentPassword": "old-password",
    "newPassword": "new-secure-password"
  }'

Forgot Password

curl -X POST https://api.otms.transportial.com/api/user/forgot \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com"
  }'

Recover Password

Use the token from the reset email:

curl -X POST https://api.otms.transportial.com/api/user/recover \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token",
    "newPassword": "new-secure-password"
  }'

User Management

Invite a User

Invite someone to join your platform:

curl -X POST https://api.otms.transportial.com/api/user/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "email": "colleague@acme-logistics.com",
    "firstName": "John",
    "lastName": "Smith"
  }'

Block / Unblock Users

# Block a user
curl -X POST "https://api.otms.transportial.com/api/user/block/{userId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Unblock a user
curl -X POST "https://api.otms.transportial.com/api/user/unblock/{userId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

List Users

curl -X GET "https://api.otms.transportial.com/api/users/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Roles & Permissions

Roles group permissions together. Assign roles to users to control what they can access.

Create a Role

curl -X POST https://api.otms.transportial.com/api/role \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Dispatcher",
    "permissions": [
      { "name": "create:transportOrder" },
      { "name": "get:transportOrders" },
      { "name": "create:trip" },
      { "name": "get:trips" }
    ]
  }'

List Roles

curl -X GET "https://api.otms.transportial.com/api/roles/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Common Permissions

Permission	Description
`create:transportOrder`	Create transport orders
`get:transportOrders`	View transport orders
`create:trip`	Create and plan trips
`get:trips`	View trips
`create:business`	Create businesses
`get:businesses`	View businesses
`create:invoice`	Create invoices
`get:invoices`	View invoices
`browse:app-store`	View available apps
`install:app`	Install apps
`create:chauffeur:activity`	Manage driver scheduling

List All Available Permissions

curl -X GET https://api.otms.transportial.com/api/permissions \
  -H "Authorization: Bearer YOUR_TOKEN"

SAML / SSO

For enterprise single sign-on, Transportial supports SAML:

Add SAML Configuration

curl -X POST https://api.otms.transportial.com/api/saml \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "entityId": "https://idp.yourcompany.com",
    "ssoUrl": "https://idp.yourcompany.com/saml/sso",
    "certificate": "MIICpDCCAYwCCQ..."
  }'

Get Platform SAML Metadata

curl -X GET https://api.otms.transportial.com/api/saml/platformSamlMetadata \
  -H "Authorization: Bearer YOUR_TOKEN"

Push Notifications (FCM)

curl -X POST https://api.otms.transportial.com/api/user/fcm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "token": "fcm-device-token"
  }'

Next Steps

Set up your platform with the Onboarding guide
Manage your team with Teams
Explore the full API Reference for all user endpoints