# 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.

## Login

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


```bash
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:**


```json
{
  "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...
```

## OTP Login

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


```bash
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

Register through the portal:

- **Standard:** [portal.otms.transportial.com/auth/register](https://portal.otms.transportial.com/auth/register)
- **Developer:** [portal.otms.transportial.com/auth/developer/register](https://portal.otms.transportial.com/auth/developer/register)


### API Registration


```bash
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


```bash
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


```bash
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


```bash
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:


```bash
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


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

### List All Sessions


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

### Logout


```bash
# 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


```bash
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


```bash
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:


```bash
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:


```bash
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


```bash
# 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


```bash
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


```bash
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


```bash
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


```bash
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


```bash
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


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

## Push Notifications (FCM)

Register a device for push notifications:


```bash
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](/guides/onboarding)
- Manage your team with [Teams](/guides/teams-and-organizations)
- Explore the full [API Reference](/apis) for all user endpoints