Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer <token>

There are two ways to authenticate:

Register an Account

Create a new account via the API. Returns JWT tokens automatically so you can start making API calls immediately.

Request Body:

{
  "username": "myuser",
  "email": "user@example.com",
  "password": "securepassword"
}

Response (201):

{
  "success": true,
  "userId": 42,
  "username": "myuser",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "a1b2c3d4e5f6...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Option 1: JWT Login (Recommended)

Authenticate with your username and password to receive a short-lived JWT access token and a refresh token. This is the standard approach for apps, scripts, and integrations.

Request Body:

{
  "username": "your_username",
  "password": "your_password",
  "scopes": ["team-data:read", "team-data:write"]  // optional, defaults to all
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "a1b2c3d4e5f6...",
  "expiresIn": 3600,
  "scopes": ["team-data:read", "team-data:write"],
  "tokenType": "Bearer"
}

Request Body:

{
  "refreshToken": "a1b2c3d4e5f6..."
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "new_refresh_token...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Refresh tokens are rotated on each use — the old token is revoked and a new one is returned.

Full example:

# 1. Login (form-encoded — recommended, avoids shell escaping issues)
curl -X POST https://visimade.com/api/auth/token \
  -d "username=myuser&password=mypass"

# Or with JSON:
curl -X POST https://visimade.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "myuser", "password": "mypass"}'

# 2. Use the access token for API calls
curl https://visimade.com/api/pages/123/team-data/tasks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# 3. When the access token expires, refresh it
curl -X POST https://visimade.com/api/auth/token/refresh \
  -d "refreshToken=a1b2c3d4e5f6..."

Shell escaping tip: Auth endpoints accept both application/json and form-encoded (application/x-www-form-urlencoded) bodies. When using curl, prefer form-encoded (-d "username=foo&password=bar") — bash shell expansion can mangle JSON when passwords contain !, $, \, or backticks.

Option 2: Persistent API Tokens

For long-running servers or CI/CD pipelines, you can create persistent API tokens in your account settings. These vm_ tokens don't expire unless you set an expiration or revoke them manually.

Authorization: Bearer vm_your_token_here

Scopes

Both JWT and persistent tokens support scoped access: