🔐 K-Series Authentication Error Guide

Diagnose and resolve common OAuth 2.0 / OIDC authentication errors across K-Series environments.

v2.0 · Updated

🔍

📋 Environment Quick Reference

Environment	Authorization Endpoint	Token Endpoint	Client ID Prefix
Trial	`auth.lsk-trial.app`	`auth.lsk-trial.app`	`devp-v2-demo`
Production	`auth.lsk-prod.app`	`auth.lsk-prod.app`	`devp-v2`

No errors match your search. Try different keywords.

Authorization Errors

🌐 Wrong Environment

Environment Mismatch #

⚠️ Warning

Always verify your authorization URL matches your client's environment. Mixing trial and production credentials is a common source of Client not found errors.

Client not found error screenshot — We are sorry… Client not found

Error Details & Example

Error: Client not found

Client ID: devp-v2-demo-dasxtrial-b69ffe954c5cd33c57a79a94780eb2ab — belongs to trial (prefix: devp-v2-demo)
Authorization URL used:

https://auth.lsk-prod.app/realms/k-series/protocol/openid-connect/auth
  ?response_type=code
  &client_id=devp-v2-demo-dasxtrial-b69ffe954c5cd33c57a79a94780eb2ab
  &scope=financial-api
  &redirect_uri=https%3A%2F%2Flocalhost%2F

📝 Note

The URL targets lsk-prod.app (production), but the client_id is a trial client. These environments are isolated — clients are not shared.

✅ Resolution

🛠 Fix

Match your authorization URL to your client's environment. Check the client ID prefix: devp-v2-demo → use auth.lsk-trial.app; no demo suffix → use auth.lsk-prod.app. Refer to the Environment Quick Reference table above.

🔗 Incorrect Redirect URI

URI Mismatch #

⚠️ Caution

The redirect_uri must be an exact string match — including protocol, path, and trailing slash. Even a single missing / will cause the request to fail.

Invalid redirect URI error screenshot — We are sorry… Invalid parameter: redirect_uri

Error Details & Example

Error: Invalid parameter: redirect_uri

Context	Value
Used in request	`https://localhost`
Registered on server	`https://localhost/`

Common causes:

Trailing slash missing or incorrectly added
Typo or character encoding mismatch
Using http:// instead of https://

✅ Resolution

🛠 Fix

Copy the exact redirect URI from the API credential provisioning email or developer portal. Compare character-by-character — pay attention to trailing slashes, protocol scheme, and URL encoding. If you need the redirect URI updated, contact TPS with your client ID.

🔑 Invalid Scope

Scope Error #

📌 Important

Scope names must exactly match the values configured on the authorization server. Underscores vs. hyphens are a frequent mistake.

Error Details, Valid Scopes & Example

Error URL returned:

https://localhost/?error=invalid_scope
  &error_description=Invalid+scopes%3A+financial-api+items+offline_access+orders-api
  &iss=https%3A%2F%2Fauth.lsk-prod.app%2Frealms%2Fk-series

Common mistakes:

❌ Invalid	✅ Correct
`financial_api`	`financial-api`
`items-api`	`items`

Valid scopes for K-Series clients:

financial-api
orders-api
items
offline_access
staff-api

💡 Tip

Multiple scopes must be space-delimited before URL encoding. Example: scope=financial-api%20orders-api%20items

✅ Resolution

🛠 Fix

Cross-reference your requested scopes against the valid scope list above. Ensure you're using hyphens where required (not underscores) and that scope names are space-separated in the raw value before URL encoding. Only request scopes your client has been provisioned for.

👤 Incorrect K-Series User Credentials

Login Error #

⚠️ Warning

Trial and production environments maintain separate user directories. Production credentials will not work in a trial environment and vice versa.

Invalid login credentials screenshot — Invalid username or password

Possible Causes

Username or password is incorrect
Using production credentials in a trial environment (or vice versa)
The account does not exist in the selected product/realm
Account may be locked or disabled

✅ Resolution

🛠 Fix

Confirm you're logging in to the correct environment (trial vs. production). Verify the username and password. If the account may be locked, contact TPS to check the account status in the appropriate realm.

Token Exchange Errors

⏱️ Invalid Code Grant

Token Exchange 400 #

⚠️ Caution

Authorization codes are single-use and expire in approximately 15 seconds. Do not reuse or cache them.

Possible Causes & Response

Possible Causes:

Authorization code has expired (~15 second window)
Code has already been used (codes are one-time use)
Code is malformed, truncated, or contains a typo

Response:

{
  "error": "invalid_grant",
  "error_description": "Code not valid"
}

✅ Resolution

🛠 Fix

Restart the authorization flow to obtain a fresh authorization code. Ensure your application exchanges the code for tokens immediately after receiving it — automate this step rather than copying manually. Never reuse a code.

🔒 Invalid Client or Credentials

Client Auth 401 #

📌 Important

The Authorization header must be present and correctly formatted as Basic base64(client_id:client_secret).

Possible Causes & Response

Possible Causes:

Authorization header is missing entirely
Credentials are not Base64-encoded
client_id or client_secret is incorrect
Using the wrong client credentials for the environment

Response:

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

✅ Resolution

🛠 Fix

Generate the Base64 value and set the header correctly:

# Generate the Base64 value
echo -n "client_id:client_secret" | base64

# Set the header
Authorization: Basic <base64_value>

💡 Tip

Double-check you're using the correct client credentials for the target environment. The -n flag in echo is critical — without it, a newline character is appended, producing an incorrect Base64 value.

↔️ Incorrect Redirect URI (Token Exchange)

URI Mismatch 400 #

⚠️ Warning

The redirect_uri in the token exchange request must be identical to the one used in the original authorization request — even though no redirect actually occurs at this step.

Possible Causes & Response

Possible Causes:

redirect_uri in the token request doesn't match the authorization step
Trailing slash added or removed between steps
URL encoding differences between requests

Response:

{
  "error": "invalid_grant",
  "error_description": "Incorrect redirect_uri"
}

✅ Resolution

🛠 Fix

Use the exact same redirect_uri value in both your authorization request and your token exchange request. Store the value in a variable or constant to prevent drift. Compare the raw strings — even URL encoding differences will cause a mismatch.

Refresh Token Errors

🔁 Invalid Refresh Token

Refresh 400 #

⚠️ Caution

Refresh tokens are long-lived but not permanent. An expired, reused, or malformed refresh token cannot be recovered — a full re-authentication is required.

Possible Causes

Refresh token has passed its expiry window
Token was already used and the server enforces rotation
Refresh token is malformed or contains a transcription error
Token belongs to a different client or environment

✅ Resolution

🛠 Fix

Re-authenticate the user through the full authorization flow to obtain a new refresh token. Implement token rotation handling in your client: when a refresh fails with invalid_grant, redirect the user back through the authorization flow automatically rather than surfacing a raw error. Ensure offline_access is included in your requested scopes to receive refresh tokens.

Client Configuration Errors

🚫 Unauthorized Client

Grant Type 400 #

📌 Important

This error occurs when the client attempts to use a grant_type that has not been enabled for it on the authorization server.

Possible Causes & Response

Possible Causes:

Client is not configured for the authorization_code grant type
Client is attempting client_credentials flow but is only approved for auth code flow
Attempting to use refresh_token grant but rotation or refresh is not enabled
Client configuration was changed or provisioned incorrectly

Response:

{
  "error": "unauthorized_client",
  "error_description": "Client not allowed for direct access grants"
}

✅ Resolution

🛠 Fix

Confirm the grant type(s) your client has been provisioned for. If you require a different grant type (e.g., client_credentials), contact TPS to update your client configuration. The most common K-Series integration flow is authorization_code with PKCE.