Authentication

All Tether API endpoints (except QR codes and the public branding endpoint) require a Bearer token. This page explains how to obtain and use tokens.

Obtaining a token

Post credentials to the login endpoint using application/x-www-form-urlencoded encoding (not JSON):

httpCopy
POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin%40atechsolutions.org&password=yourpassword

Successful response:

jsonCopy
{{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}}

Failed response (wrong credentials):

jsonCopy
{{
  "detail": "Incorrect email or password"
}}

Using the token

Include the token in the Authorization header of every request:

httpCopy
GET /api/assets
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token expiry

Tokens are valid for 7 days from the time of issue. After expiry, the API returns 401 Unauthorized. The client must log in again to get a new token.

If SECRET_KEY is rotated in .env and Tether restarted, all existing tokens are immediately invalidated and all users must log in again.

Tenant scoping

The API determines the active tenant from the HTTP Host header of the request:

MSP staff can also scope to a specific tenant from the root domain by adding a query parameter:

httpCopy
GET /api/assets?tenant=acme
Host: atechsolutions.org
Authorization: Bearer {msp-token}
# Returns assets scoped to the "acme" tenant

Get current user

httpCopy
GET /api/auth/me
Authorization: Bearer {token}

# Response:
{{
  "id": 1,
  "name": "Sarah Chen",
  "email": "sarah@acme.com",
  "role": "client_admin",
  "is_msp_staff": false,
  "tenant_id": 5,
  "tenant_slug": "acme",
  "permissions": [
    "assets.view", "assets.create", "assets.edit",
    "assets.delete", "assets.checkout", "assets.checkin",
    "assets.import", "assets.export", "categories.manage",
    "locations.manage", "employees.manage", "users.manage",
    "reports.view", "settings.manage"
  ]
}}

Change password

httpCopy
POST /api/auth/change-password
Authorization: Bearer {token}
Content-Type: application/json

{{
  "current_password": "oldpassword",
  "new_password": "newstrongpassword"
}}

# Success: 200 OK
# Wrong current password: 400 Bad Request

Public endpoints (no auth required)

Error response format

All API errors use a consistent format:

jsonCopy
{{
  "detail": "Human-readable error message"
}}