> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard user token

> Authenticate a dashboard user with username and password; receive a JWT.

### Overview

Authenticates a **dashboard user** by username and password and returns a signed JWT with `UserId`, `CompanyId`, and `TimeZone` claims.

<Note>
  A V2 version of this endpoint is available: [User token](/v2/api-reference/post-authentication-token-user). New integrations should prefer V2.
</Note>

### Endpoint

`POST /api/Authentication/token/user`

### Authentication

Not required (public endpoint).

### Request headers

| Header       | Required | Description                         |
| ------------ | -------- | ----------------------------------- |
| Content-Type | Yes      | `application/x-www-form-urlencoded` |

### Request body (form)

<ParamField body="UserName" type="string" required>
  Telemax account username (same as web login).
</ParamField>

<ParamField body="Password" type="string" required>
  Account password.
</ParamField>

### Example request body

```text theme={null}
UserName=integration.reader@acmefleet.com.au&Password=K7mP2vL9qW4nR8xT
```

### Response

**200 OK** — `JwtTokenResponse`

<ResponseField name="access_token" type="string">
  Bearer token for subsequent API calls.
</ResponseField>

<ResponseField name="token_type" type="string">
  Always `bearer`.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Token lifetime in seconds (float).
</ResponseField>

### Example response

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJDb21wYW55SWQiOiIxMiIsIlVzZXJJZCI6ImExYjJjZDQwLWU1ZjYtNDc4OS1hYmNkLWVmMDEyMzQ1Njc4OSIsIlRpbWVab25lIjoiQXVzdHJhbGlhL1N5ZG5leSIsIm5iZiI6MTcxMjQ4MDAwMCwiZXhwIjoxNzEyNTY2NDAwLCJpYXQiOjE3MTI0ODAwMDAsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0OjcyOTkiLCJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo3Mjk5In0.signature",
  "token_type": "bearer",
  "expires_in": 86399.0
}
```

### Error responses

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| 401    | Invalid username or password, or user has no company assignment |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.telemax.com.au/api/Authentication/token/user" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "UserName=integration.reader@acmefleet.com.au" \
    --data-urlencode "Password=K7mP2vL9qW4nR8xT"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.telemax.com.au/api/Authentication/token/user", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      UserName: "integration.reader@acmefleet.com.au",
      Password: "K7mP2vL9qW4nR8xT",
    }),
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api.telemax.com.au/api/Authentication/token/user',
      data={
          'UserName': 'integration.reader@acmefleet.com.au',
          'Password': 'K7mP2vL9qW4nR8xT',
      },
  )
  ```
</CodeGroup>


## OpenAPI

````yaml openapi.yaml POST /api/authentication/token/user
openapi: 3.1.0
info:
  title: Telemax External API (V1)
  version: '2026-04-14'
  description: >
    Telemax External API — fleet telemetry, vehicle commands, and integrations.


    **Base URL:** `https://api.telemax.com.au`


    **Authentication:** All routes require a `Bearer` JWT unless marked
    `[AllowAnonymous]`.

    Obtain tokens via `/api/Authentication/token/api-key` or
    `/api/Authentication/token/user`.


    **POST-first architecture:** Almost all data endpoints use `POST` with
    query-string parameters.

    The two exceptions using `GET` are `GetDeviceId` and `GET
    /api/devices/{id}/dtc-codes`.


    **API versioning:** All responses will include an `X-API-Version` header
    containing the

    date-based version string (e.g. `2026-04-14`). See the
    [Changelog](/v1/changelog) for

    the deprecation policy and version history.


    For full documentation including error handling, pagination, and known field
    quirks, see [docs.telemax.com.au](https://docs.telemax.com.au).
servers:
  - url: https://api.telemax.com.au
security:
  - BearerAuth: []
paths:
  /api/authentication/token/user:
    parameters: []
    post:
      summary: Authenticate with User Credentials
      description: >-
        Get access token via username/password combination. Uses the same
        credentials as the main Telemax account.
      parameters:
        - name: Content-Type
          in: header
          required: false
          description: Standard and must keep it as it is.
          example: application/x-www-form-urlencoded
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Username
                  example: john_doe@email.com
                password:
                  type: string
                  description: Password
                  example: secure_password123
              required:
                - username
                - password
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: JWT access token
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: number
                    format: float
                    description: >-
                      Token lifetime in seconds. Default is 86399.0 (≈24 hours).
                      Cache and reuse this token until near expiry — do not
                      request a new token per API call.
                    example: 86399
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: >
        **401 Unauthorized** — JWT is missing, expired, or malformed.

        The JWT bearer middleware rejects the request before it reaches the
        controller.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: AUTHENTICATION
            code: TOKEN_EXPIRED
            description: >-
              The access token has expired. Request a new token using
              /api/authentication/token/user or
              /api/authentication/token/api-key.
            requestId: req_7f3a2b1c
            docUrl: https://docs.telemax.com.au/errors#token-expired
    TooManyRequests:
      description: >
        **429 Too Many Requests** — Rate limit exceeded. Check the Retry-After
        header for the number of seconds to wait before retrying.

        Use exponential backoff: wait Retry-After seconds, then double the
        interval on each subsequent 429.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: RATE_LIMIT
            code: RATE_LIMIT_EXCEEDED
            description: Too many requests. Wait 30 seconds before retrying.
            requestId: req_6d2f8b4a
            docUrl: https://docs.telemax.com.au/errors#rate-limit
    InternalServerError:
      description: >
        **500 Internal Server Error** — An unexpected error occurred. Include
        the requestId when contacting support.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: SERVER_ERROR
            code: INTERNAL_ERROR
            description: >-
              An unexpected error occurred. Please try again or contact support
              with the requestId.
            requestId: req_1e5a3c7d
            docUrl: https://docs.telemax.com.au/errors#server-error
  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per minute for this token.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Number of requests remaining in the current rate limit window.
      schema:
        type: integer
        example: 47
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) at which the current rate limit window resets.
      schema:
        type: integer
        example: 1746000060
    Retry-After:
      description: Number of seconds to wait before retrying after a 429 response.
      schema:
        type: integer
        example: 30
  schemas:
    ApiError:
      type: object
      description: Standard error response returned by all API endpoints.
      properties:
        type:
          type: string
          description: >-
            Error category (e.g. AUTHENTICATION, AUTHORIZATION, NOT_FOUND,
            VALIDATION, RATE_LIMIT, SERVER_ERROR).
          example: AUTHENTICATION
        code:
          type: string
          description: Machine-readable error code within the category.
          example: TOKEN_EXPIRED
        description:
          type: string
          description: Human-readable explanation of the error and how to resolve it.
          example: The access token has expired. Request a new token.
        requestId:
          type: string
          description: Unique request identifier for support correlation.
          example: req_7f3a2b1c
        docUrl:
          type: string
          format: uri
          description: Link to the relevant error documentation page.
          example: https://docs.telemax.com.au/errors#token-expired
      required:
        - type
        - code
        - description
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT Bearer token obtained from `POST /api/authentication/token/user` or
        `POST /api/authentication/token/api-key`.


        **Lifetime:** ~24 hours (86,399 seconds). Cache the token and reuse it.
        Re-authenticate 5 minutes before expiry.


        **Scoping:**

        - User tokens are scoped to a single company.

        - API key tokens may restrict access to a vehicle allowlist and/or
        action set (see token claims).


        **No refresh endpoint** — re-authenticate with your credentials when the
        token expires.

````