Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Termix-SSH/Termix/llms.txt

Use this file to discover all available pages before exploring further.

The Termix API supports two authentication methods: short-lived JWTs issued at login, and long-lived API keys created through the admin panel. Both are passed the same way — as an Authorization: Bearer header. You can also use the jwt cookie that the login endpoint sets automatically, which is convenient for browser-based clients.

​
Method 1 — Login to get a JWT

Send a POST request to /users/login with your username and password. On success, Termix returns a JSON body and sets a jwt cookie. You can use either the cookie (for browser requests) or extract the token from the Set-Cookie header for programmatic use.
1

Send the login request

curl -c cookies.txt -X POST http://your-server:8080/users/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'
2

Read the response

A successful login returns HTTP 200 with the following body and a Set-Cookie: jwt=... header:
{
  "success": true,
  "is_admin": true,
  "username": "admin"
}
The JWT is set as an httpOnly cookie named jwt. Its maxAge is 24 hours by default, or 30 days if rememberMe is true.
3

Use the token on subsequent requests

Pass the JWT as a Bearer token in the Authorization header:
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8080/users/me
Or rely on the cookie if your HTTP client manages cookies automatically:
curl -b cookies.txt http://your-server:8080/users/me

​
Login request body

FieldTypeRequiredDescription
usernamestringYesThe account username.
passwordstringYesThe account password.
rememberMebooleanNoExtend the session to 30 days instead of the default 24 hours.

​
Login error codes

StatusMeaning
400username or password is missing or empty.
401Credentials are wrong, or the session has expired.
403Password authentication is disabled on this instance, or the account uses OIDC-only login.
429Too many failed attempts from this IP or for this username. The response includes remainingTime in milliseconds.
500Internal error — check the Termix logs.
The login endpoint is rate-limited. After repeated failures from the same IP or for the same username, the endpoint returns 429 and locks out further attempts for a cooldown period.

​
TOTP (two-factor authentication)

If the account has TOTP enabled and the device is not trusted, the login response returns a temporary token instead of a full session token: 
{
  "success": true,
  "requires_totp": true,
  "temp_token": "eyJ...",
  "rememberMe": false
}
You must complete TOTP verification using POST /users/totp/verify with the temp_token before you receive a usable session token.

​
Method 2 — API keys

API keys are long-lived tokens suitable for automation, scripts, and CI/CD. They are managed by admins at Settings → API Keys in the Termix UI, or via the API at POST /users/api-keys. All Termix API keys start with the prefix tmx_. The full token is shown only once when created and is never retrievable again.

​
Creating an API key

curl -X POST http://your-server:8080/users/api-keys \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy-key",
    "userId": "USER_ID",
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
The response includes the full token once: 
{
  "id": "abc123",
  "name": "ci-deploy-key",
  "userId": "USER_ID",
  "username": "deploy-user",
  "tokenPrefix": "tmx_abc12345",
  "createdAt": "2026-05-09T12:00:00.000Z",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "token": "tmx_abc12345678901234567890abcdef1234567890abcdef1234"
}
Copy the token value immediately. Termix stores only a bcrypt hash of the token and cannot display it again. If you lose it, delete the key and create a new one.

​
Using an API key

Pass the API key as a Bearer token exactly like a JWT: 
curl -H "Authorization: Bearer tmx_abc12345678901234567890abcdef1234567890abcdef1234" \
  http://your-server:8080/users/me
API keys do not carry a user session and do not unlock the user’s encrypted data key. If you need to access encrypted SSH credentials, use a JWT obtained through the normal login flow instead.

​
API key expiry

When you create a key, the expiresAt field is optional. Omitting it creates a key that never expires. If you provide a date, the key stops working after that timestamp and returns 401 API key has expired.

​
OIDC users

Users who sign in through an OIDC provider (such as Authentik, Keycloak, or Auth0) can also generate API keys from the admin panel. Their API keys work identically to those of password-based users.
OIDC users who also have a local password set (dual-auth accounts) can log in via either method and receive a standard JWT.

​
Token usage reference

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8080/users/me

​
Error reference

StatusCode in bodyMeaning
401—Token is missing, invalid, or expired.
401SESSION_EXPIREDThe session associated with this JWT has expired.
401SESSION_NOT_FOUNDThe session was revoked (e.g., user logged out on another device).
401TOTP_REQUIREDThe token is a pending TOTP token; complete verification first.
403—Valid token, but the account lacks the required permissions.
429—Rate-limited on the login endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us