Authentication Documentation

Overview

TendedLoop supports four authentication methods, each designed for different use cases. Choose the method that best fits your integration scenario.

JWT Authentication

JWT (JSON Web Token) is the primary authentication method for TendedLoop. Authenticate with your email and password to receive a short-lived access token and a long-lived refresh token.

Login

Send a POST request to /api/auth/login with your credentials. On success, you receive an access token (15-minute expiry) and a refresh token (30-day expiry).

cURL Login request

curl -X POST https://api.tendedloop.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourcompany.com",
    "password": "your-password"
  }'

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "clx1abc...",
      "email": "admin@yourcompany.com",
      "name": "Jane Admin",
      "roles": ["ADMIN"]
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

Using the access token

Include the access token in the Authorization header of all subsequent requests:

curl https://api.tendedloop.com/api/dashboard/overview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token refresh

When the access token expires, use the refresh token to obtain a new pair without re-authenticating:

curl -X POST https://api.tendedloop.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

JS Node.js example

const response = await fetch('https://api.tendedloop.com/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'admin@yourcompany.com',
    password: 'your-password',
  }),
});

const { data } = await response.json();
const { accessToken, refreshToken } = data.tokens;

// Use the access token for subsequent requests
const dashboard = await fetch('https://api.tendedloop.com/api/dashboard/overview', {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});

const result = await dashboard.json();
console.log(result.data);

API Keys

API keys provide a simple, long-lived authentication method ideal for server-to-server integrations, CI/CD pipelines, and backend services. Unlike JWT tokens, API keys do not expire automatically.

Creating an API key

1. Navigate to Integrations > API Keys in the admin dashboard.
2. Click Create API Key and assign a descriptive name.
3. Select the scoped permissions (read, write, webhooks:manage).
4. Copy the generated key immediately; it is only shown once.

Using an API key

Include your API key in the X-API-Key header:

curl https://api.tendedloop.com/api/dashboard/overview \
  -H "X-API-Key: tl_k_a1b2c3d4e5f6..."

JS Node.js example

const response = await fetch('https://api.tendedloop.com/api/dashboard/overview', {
  headers: {
    'X-API-Key': process.env.TENDEDLOOP_API_KEY,
  },
});

const { data } = await response.json();
console.log(data);

OAuth (SSO)

TendedLoop supports Google and Microsoft OAuth for enterprise single sign-on. Users authenticate with their identity provider and receive JWT tokens for API access. On first login, a trial tenant is automatically created.

curl -X POST https://api.tendedloop.com/api/auth/google \
  -H "Content-Type: application/json" \
  -d '{
    "credential": "eyJhbGciOiJSUzI1NiIs..."
  }'

{
  "success": true,
  "data": {
    "user": {
      "id": "clx1abc...",
      "email": "user@company.com",
      "name": "Jane Smith",
      "roles": ["ADMIN"]
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    },
    "isNewUser": false
  }
}

curl -X POST https://api.tendedloop.com/api/auth/microsoft \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGci..."
  }'

Magic Links

Magic links provide passwordless authentication by sending a one-time login link via email. This is the primary auth method for operators and technicians who access TendedLoop from their mobile devices.

Step 1: Request a magic link

Send the user's email to request a magic link. The user receives an email with a unique login URL.

curl -X POST https://api.tendedloop.com/api/auth/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "technician@yourcompany.com"
  }'

Response

{
  "success": true,
  "data": {
    "message": "Magic link sent to your email"
  }
}

Step 2: Verify the token

When the user clicks the link in their email, the token is verified and JWT tokens are returned. The magic link token expires after 15 minutes.

curl https://api.tendedloop.com/api/auth/magic-link/verify?token=mlk_a1b2c3d4...

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "clx1abc...",
      "email": "technician@yourcompany.com",
      "roles": ["TECHNICIAN"]
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

Role-Based Access

TendedLoop uses role-based access control (RBAC) to determine what each user can do. Users can hold multiple roles simultaneously, and the highest privilege wins when checking permissions.

Multi-role users

A user can hold up to 3 roles (e.g., ["ADMIN", "MANAGER"]). The JWT payload includes a roles array. When an endpoint requires a specific role, TendedLoop checks if the user holds that role or a higher-privilege one.

// JWT payload structure
{
  "userId": "clx1abc...",
  "tenantId": "clx2def...",
  "roles": ["ADMIN", "MANAGER"],
  "type": "access",
  "iat": 1707820000,
  "exp": 1707820900
}

Rate Limiting

Authentication endpoints are rate-limited to prevent brute-force attacks and abuse. When limits are exceeded, the API returns a 429 Too Many Requests response.

Rate limit response

{
  "success": false,
  "error": "Too many attempts. Please try again later.",
  "code": "RATE_LIMITED"
}

Error Codes

Authentication errors follow a consistent response format. Use the HTTP status code and the code field to handle errors programmatically.

{
  "success": false,
  "error": "Invalid or expired token",
  "code": "UNAUTHORIZED"
}

{
  "success": false,
  "error": "Insufficient permissions",
  "code": "FORBIDDEN"
}

{
  "success": false,
  "error": "Too many attempts. Please try again later.",
  "code": "RATE_LIMITED"
}