🔐 API Authentication & Error Codes

🔍 Contents

Requirements
Authentication (HTTP Basic Auth)
Examples by tool (cURL, Postman, Power Automate, Python)
Media Types (Content-Type & Accept)
Error Codes & Causes
Troubleshooting Checklist
FAQ

Requirements

🔐 Dedicated API user per tenant (not per individual employee).
ℹ️ Note: Changes to the API user (e.g., password changes) can only be made by ValueStreamer Support.

🌐 HTTPS only: https://api-<tenant>.valuestreamer.de/api/

🧪 A tool to execute requests (e.g., Postman, Swagger UI, Power Automate, Python, …).

Authentication (HTTP Basic Auth)

The REST API uses HTTP Basic Auth. Username and password are Base64-encoded and sent in the Authorization header.

Header example:

Authorization: Basic <Base64(username:password)>

✨ Tip: Test your credentials first with a simple GET request (e.g., /exchange/teams).

⚠️ Warning: There is no expiration date for the API user. Still, treat credentials as secrets.

Examples by Tool

cURL

curl -X GET \
  "https://api-<tenant>.valuestreamer.de/api/exchange/teams" \
  -H "Authorization: Basic <BASE64>" \
  -H "Accept: application/json"

Postman

Auth → Type: Basic Auth → Enter username/password.
Headers → Set Accept / Content-Type according to endpoint (see below).

Power Automate (HTTP action)

Enter method & URL.
Headers: Authorization: Basic <BASE64>, Content-Type: …, Accept: …
Body: JSON according to endpoint schema.

Python (requests)

import requests
from requests.auth import HTTPBasicAuth

url = "https://api-<tenant>.valuestreamer.de/api/exchange/teams"
r = requests.get(url, auth=HTTPBasicAuth("<USER>", "<PASS>"))
print(r.status_code, r.json())

Media Types (Content-Type & Accept)

The API uses version-specific media types. Set Accept and, if required, Content-Type according to the module:

Module / Context	Accept / Content-Type
KPI v2	application/vs.v2.0+json
List Editor v2	application/vs.v2.0+json
Process Board v1	application/vs.pb.v1.0.0+json
Task Board v1	application/json (unless otherwise stated)
Deviation / Countermeasures v1	usually application/json or module-specific variants

✨ Tip: The YAML specifications for each module list the exact media types for every endpoint.

Error Codes & Causes

Example response:

{
  "errorId": 0,
  "errorMessage": "string"
}

Code	Meaning	Typical Cause	Solution
200/201	OK / Created	Request correct	—
204	Record deleted	Delete successful, no body	—
400	Bad Request	Invalid body, missing fields, wrong UUID/data type	Check request schema against YAML; set required fields; fix data types
401	Not authorized	Wrong/missing Basic Auth	Check username/password; correct Base64; use HTTPS only
404	Not found	Resource/ID does not exist or wrong path	Verify IDs/URL; perform GET on meta-endpoints first
409	Conflict	Rule violation (e.g., duplicate, invalid state)	Adjust payload; follow business rules from documentation/YAML
415	Unsupported Media Type	Wrong Content-Type/Accept	Set media type according to module (see table above)
422	Unprocessable Entity	Valid JSON, but logically inconsistent	Check required relationships/validations (e.g., status/message)
500	Internal Server Error	Unexpected error	Minimize request, retry later; contact support with `errorId`, timestamp, and payload

ℹ️ Note: Not all endpoints use all codes; the respective OpenAPI specification (YAML/Swagger) is authoritative.

Troubleshooting Checklist

✅ Correct Auth? Basic Auth active, Base64 without line breaks.
✅ HTTPS only.
✅ Correct media types (Accept/Content-Type).
✅ Required fields per YAML set?
✅ Validate IDs (Team/KPI/List/Phase etc. via meta-GET).
✅ Follow business rules (e.g., status change requires statusMessage).
✅ Test with minimal payload, then add fields gradually.
✅ Document error details: status, errorId, errorMessage, timestamp, request ID (if available).

FAQ

Do I have individual API users per employee?
→ No. Each tenant has one dedicated API user. Personal logins are not intended for API access.

Does the API support Webhooks or token-based authentication?
→ Not currently. Only HTTP Basic Auth over HTTPS is supported.

Where can I find the full list of error codes and media types?
→ In the YAML files of the respective modules; example responses are also available in Swagger or the PDF documentation.

Why do I get a 401 even with correct credentials?
→ Usually the header is missing or the Base64 string contains special characters/whitespace. In Postman, use Basic Auth mode (don’t encode manually).

When should I use 415 vs. 400?
→ 415 = header/format is wrong; 400 = format is correct but content/schema is invalid.