Forms of authentication

This document describes how to obtain authentication tokens for the Workforce API and how to use the Auth Integration API for server-side deployments. Choose the option that best fits your use case.

Option 1: Direct Authentication (Public User / Popup Chat)

This option is intended for public users, such as when using the chat popup widget on websites. The authentication request should be performed server-side, not in the client browser. This method is not recommended for most clients, but is available for those who do not have their own backend.

1. Authentication & Token Handling (Server-Side)

Your server application should perform the login request to the Auth API, using a system/public user:

 
curl --location 'https://app-eu.workforcehub.ai/api/latest/auth/login' \ 
 
 --header 'Content-Type: application/json' \ 
 
 --data '{"username": "<your-username>", "password": "<your-password>"}' 
 

Response Example

 
{ 
 
 "access_token": "<JWT token>", 
 
 ... 
 
} 
 

After a successful login, your server receives an access_token. The server should then set this token as a secure cookie for the client. For example (JavaScript syntax, adapt as needed for your backend):

 
document.cookie = `wfh-token=${access_token}; path=/; SameSite=None; Secure`; 
 

This ensures the token is stored securely and will be automatically available for the Chat pop-up on the frontend.

Save the access_token value. You will use it as a Bearer token in the Authorization header for subsequent API or WebSocket requests.

Option 2: Server-Side Integration via Auth Integration API

Deploy and use our Auth Integration API microservice to manage user tokens, caching, and automatic user creation. This is recommended for server-side applications and backend integrations.

Features

• POST /auth-integration/get-token: Returns an access token for a given user (by email).
• Per-user in-memory token cache: Each user's token is cached and reused until it is close to expiry.
• Automatic token renewal: Master token is refreshed automatically when it's about to expire.
• User auto-creation: If a user does not exist, the service will create the user and then fetch the token.

1. Deploy the Service

a) Docker (Recommended)

 
docker run -p 8080:8080 \ 
 
 -e WORKFORCE_API_BASE_URL='https://app-eu.workforcehub.ai/api/latest' \ 
 
 -e WORKFORCE_API_USERNAME='<service-username>' \ 
 
 -e WORKFORCE_API_PASSWORD='<service-password>' \ 
 
 -e WORKFORCE_API_TENANT_ID='<tenant-id>' \ 
 
 -e WORKFORCE_API_USER_REGISTRATION='true' \ 
 
 thingsolver/wf-auth-integration:v2.9.0 
 

b) Local (Go)

1. Install Go 1.24 or newer.
2. Set the environment variables as above.
3. Ask us for binary

4. Run:

   go run ./cmd/main.go 
    

2. Obtain a User Token

Send a POST request to your deployed service:

 
curl --location 'http://<your-server>:8080/auth-integration/get-token' \ 
 
 --header 'Content-Type: application/json' \ 
 
 --data '{ 
 
   "username": "testuser", 
 
   "email": "testuser@example.com", 
 
   "first_name": "Test", 
 
   "last_name": "User" 
 
 }' 
 

Successful Response

 
{ 
 
 "access_token": "<JWT token>", 
 
 "expires_in": 3600 
 
} 
 

Error Response

 
{ 
 
 "details": "Error description" 
 
} 
 

3. Health Check

To verify the service is running:

 
curl http://<your-server>:8080/health-check 
 

Environment Variables

Set the following environment variables before running the service:

 
export WORKFORCE_API_BASE_URL='https://workforce-eu.thingsolver.com/api/latest' 
 
export WORKFORCE_API_USERNAME='<service-username>' 
 
export WORKFORCE_API_PASSWORD='<service-password>' 
 
export WORKFORCE_API_TENANT_ID='<tenant-id>' 
 
export WORKFORCE_API_USER_REGISTRATION='true' 
 

FAQ

Q: What is the difference between the two options?

• Use Option 1 if you only need a token for a single user or for client-side authentication.
• Use Option 2 if you want to automate user token management, caching, and user creation on your backend/server.

Q: What happens if a user does not exist?

• If WORKFORCE_API_USER_REGISTRATION is set to true, the service will automatically create the user and then fetch the token.
• If set to false, you will receive a 404 error if the user does not exist.

Q: How are tokens cached?

• The service caches tokens in memory per user and refreshes them before expiry for optimal performance.

For further support, contact the Things Solver team.