Token endpoint

Documentation

Token endpoint

Use this page for exact request and response formats for app tokens, user tokens, and refresh tokens.

`POST /api/Token`

Use this endpoint to get either an app token or a user token.

Item	Value
Method	`POST`
Path	`/api/Token`
Auth	No bearer token
Content-Type	`application/x-www-form-urlencoded`
Response	JSON object with `access_token`, `refresh_token`, `token_type`, `expires_in`

Request fields

Field	Required	Values	Notes
`grant_type`	Yes	`client_credentials`, `password`, `refresh_token`	Selects the auth flow.
`client_id`	Yes	API client GUID/string issued by VizSeek	Required for every flow.
`username`	Password flow only	User email address	Use with `grant_type=password`.
`password`	Password flow only	SHA-1 hex digest	Not raw text. Not base64.
`refresh_token`	Refresh flow only	Refresh token returned by a previous token response	Use with `grant_type=refresh_token`.

App token request

Use this when the endpoint only needs the API client identity.

curl -X POST "https://your-server.example.com/api/Token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID"

import requests

server = "https://your-server.example.com"
client_id = "YOUR_CLIENT_ID"

resp = requests.post(
    f"{server}/api/Token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "grant_type": "client_credentials",
        "client_id": client_id,
    },
)
resp.raise_for_status()
token_data = resp.json()
print(token_data["access_token"])

User token request

Use this when the endpoint needs a signed-in user.

POST /api/Token HTTP/1.1
Host: your-server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=YOUR_CLIENT_ID&username=user%40example.com&password=SHA1_HEX_PASSWORD

import hashlib
import requests

server = "https://your-server.example.com"
client_id = "YOUR_CLIENT_ID"
username = "[email protected]"
password = "YourPlainTextPassword"

sha1_hex = hashlib.sha1(password.encode("utf-8")).hexdigest()

resp = requests.post(
    f"{server}/api/Token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "grant_type": "password",
        "client_id": client_id,
        "username": username,
        "password": sha1_hex,
    },
)
resp.raise_for_status()
token_data = resp.json()
print(token_data["access_token"])
print(token_data["refresh_token"])

Refresh-token request

Use this when your access token has expired and you still have a valid refresh token.

curl -X POST "https://your-server.example.com/api/Token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

resp = requests.post(
    f"{server}/api/Token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={
        "grant_type": "refresh_token",
        "client_id": client_id,
        "refresh_token": existing_refresh_token,
    },
)
resp.raise_for_status()
new_token_data = resp.json()

Response format

Typical response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "95c0858d-b0a0-4110-a81d-18978ae78ec0",
  "token_type": "bearer",
  "expires_in": "1799"
}

Field meanings

Field	Meaning
`access_token`	JWT bearer token used in the `Authorization` header
`refresh_token`	Opaque token used only with `grant_type=refresh_token`
`token_type`	Always `bearer`
`expires_in`	Lifetime in seconds, returned as a string

Common failure cases

client_id missing.: you did not send client_id.
'client_id' incorrect. or client_id incorrect.: the API client ID is not recognized.
User authentication failed.: wrong email, wrong password hash, or wrong client ID for that user flow.
Invalid request: missing or expired refresh token, or an unsupported grant type.