Authentication

Wallin supports three authentication mechanisms depending on the API you're using.

Agent API (Sanctum Token)

The Agent API uses Laravel Sanctum token-based authentication.

Obtaining a Token

Request:

POST /api/agent/login
Content-Type: application/json

{
  "email": "agent@example.com",
  "password": "your_password",
  "device_name": "Mobile App"
}

Response (200 OK):

{
  "token": "1|abc123defghijklmnopqrstuvwxyz",
  "user": {
    "id": 1,
    "name": "Agent Name",
    "email": "agent@example.com",
    "agent_role": "agent",
    "availability_status": "offline"
  },
  "vapid_public_key": "BG8n_..."
}

Error (401):

{
  "message": "The provided credentials are invalid."
}

The token is used in all subsequent API calls. The device_name parameter identifies the device/app for security logs.

Using the Token

Add the token to the Authorization header of all requests:

curl https://wallin.example/api/agent/conversations \
  -H "Authorization: Bearer 1|abc123defghijklmnopqrstuvwxyz"

Tokens are tied to your user and organization. If you belong to multiple organizations, use the X-Organization-Id header to specify which one.

Logging Out

Revoke the current token:

POST /api/agent/logout
Authorization: Bearer 1|abc123defghijklmnopqrstuvwxyz

Response (200):

{
  "message": "Logged out"
}

The token becomes invalid after logout.

Token Expiry

Sanctum tokens don't expire by default, but your session may be cleared if you're inactive for a long time. Re-login if you get a 401 Unauthorized response.

OTP API (API Key)

The OTP API uses a static API key passed in a custom header.

Obtaining an API Key

1. Go to /otp-applications
2. Create or select an OTP application
3. Click API Keys
4. Copy the displayed key (shown only once)

Keep this key secret. Treat it like a password — don't commit it to version control.

Using the API Key

Add the key to the X-Wallin-OTP-Key header:

curl https://wallin.example/api/v1/otp/send \
  -H "X-Wallin-OTP-Key: your_api_key"

Rotating API Keys

To invalidate the current key and issue a new one:

1. Go to /otp-applications
2. Select the app
3. Click API Keys → Generate New Key

The old key becomes invalid immediately. Update your app's configuration with the new key.

IP Allow-list

Restrict API calls to specific IP addresses for extra security:

1. Go to /otp-applications
2. Select the app
3. Click Security
4. Add trusted IP addresses
5. Save

Only requests from these IPs are accepted. All others get a 403 Forbidden response.

WhatsApp API (Sanctum Token + Tenant)

The WhatsApp API uses the same Sanctum token as the Agent API, plus tenant scoping.

Authentication

curl https://wallin.example/api/whatsapp/send-text \
  -H "Authorization: Bearer 1|abc123defghijklmnopqrstuvwxyz" \
  -H "X-Organization-Id: 5"

The X-Organization-Id header specifies which organization's business accounts to use. If omitted, your user's current organization is assumed.

Tenant Context

Wallin is multi-tenant. Your token is scoped to the organizations you belong to. If you try to access a conversation or business account from a different organization, you get a 403 Forbidden response.

Security Best Practices

1. Never hardcode tokens — Use environment variables or secure vaults
2. Use HTTPS — All API calls must be over HTTPS in production
3. Rotate OTP keys regularly — Every 90 days or after a security incident
4. Use IP allow-lists — For OTP API, restrict to your server's IP
5. Monitor token usage — Check for unusual activity at /my-team or in logs
6. Re-login before long-lived operations — If your app runs for hours, re-authenticate to ensure session freshness

Errors

CORS & Same-Origin

Wallin's API endpoints are designed for backend-to-backend calls. Browser requests (from a frontend at a different domain) may be blocked by CORS unless explicitly configured.

For browser-based SDKs, use server-to-server credentials or server proxies.