Authentication

The Telisky MDM API supports two authentication methods: browser-based cookie authentication and API token authentication for programmatic access.

Authentication Methods

1. Cookie-Based (Browser)

Used by the web portal. After login, a JWT is stored in an HttpOnly cookie.

# Login
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

# Response sets HttpOnly cookie: ts_auth=<jwt>

2. Bearer Token (API)

For scripts and integrations using API tokens:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://mdm-api.telisky.com/api/devices

Auth Endpoints

Method	Endpoint	Description
POST	/api/auth/register	Create a new account
POST	/api/auth/login	Authenticate and get session
POST	/api/auth/logout	End session
GET	/api/auth/me	Get current user profile
POST	/api/auth/refresh-token	Refresh JWT token

Login

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

{
  "email": "admin@example.com",
  "password": "SecurePass123"
}

Success Response (200):

{
  "user": {
    "id": "uuid",
    "email": "admin@example.com",
    "role": "admin",
    "tenantId": "uuid"
  },
  "token": "eyJhbG..."
}

Error Response (401):

{
  "error": "Invalid credentials"
}

API Tokens

Generate long-lived tokens for programmatic access:

Create a Token

POST /api/auth/tokens
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "name": "CI/CD Pipeline",
  "scopes": ["devices:read", "telemetry:read"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Response (201):

{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "token": "tsk_abc123...",
  "scopes": ["devices:read", "telemetry:read"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Caution

The token value is only shown once at creation time. Store it securely.

Available Scopes

Scope	Permission
devices:read	List and view devices
devices:write	Create, update, delete devices
telemetry:read	Query telemetry data
config:read	View configuration profiles
config:write	Create and deploy configurations
firmware:read	List firmware versions
firmware:deploy	Deploy firmware updates
users:read	List users
users:write	Manage users

Rate Limiting

Tier	Limit
Unauthenticated	10 requests/minute
Authenticated (Starter)	100 requests/minute
Authenticated (Pro)	1,000 requests/minute
Authenticated (Enterprise)	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1716825660

Error Responses

Status	Meaning
401	Missing or invalid authentication
403	Authenticated but insufficient permissions
429	Rate limit exceeded

All error responses follow this format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}