Workhuman Install & Auth

Overview

Configure Workhuman API access for Social Recognition, rewards, and HRIS integration. Workhuman uses OAuth 2.0 for API authentication. The API enables programmatic recognition nominations, reward redemption, and employee data sync.

Prerequisites

Workhuman enterprise account with API access enabled
OAuth client credentials from Workhuman admin portal
HTTPS endpoint for redirect URI (if using auth code flow)

Instructions

Step 1: Configure OAuth Credentials

# .env
WORKHUMAN_CLIENT_ID=your-client-id
WORKHUMAN_CLIENT_SECRET=your-client-secret
WORKHUMAN_BASE_URL=https://api.workhuman.com
WORKHUMAN_TENANT_ID=your-tenant-id

Step 2: Obtain Access Token (Client Credentials)

import axios from 'axios';

async function getWorkhmanToken(): Promise<string> {
  const { data } = await axios.post(
    `${process.env.WORKHUMAN_BASE_URL}/oauth/token`,
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.WORKHUMAN_CLIENT_ID!,
      client_secret: process.env.WORKHUMAN_CLIENT_SECRET!,
    }),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
  );
  return data.access_token;
}

Step 3: Verify Connection

const token = await getWorkhmanToken();
const api = axios.create({
  baseURL: process.env.WORKHUMAN_BASE_URL,
  headers: { Authorization: `Bearer ${token}` },
});

const { data } = await api.get('/api/v1/users/me');
console.log(`Connected as: ${data.displayName}`);

Step 4: Python Client

import requests, os

class WorkhumanClient:
    def __init__(self):
        self.base = os.environ["WORKHUMAN_BASE_URL"]
        self.token = self._authenticate()

    def _authenticate(self):
        resp = requests.post(f"{self.base}/oauth/token", data={
            "grant_type": "client_credentials",
            "client_id": os.environ["WORKHUMAN_CLIENT_ID"],
            "client_secret": os.environ["WORKHUMAN_CLIENT_SECRET"],
        })
        return resp.json()["access_token"]

    def get(self, endpoint, **params):
        return requests.get(f"{self.base}{endpoint}",
            headers={"Authorization": f"Bearer {self.token}"}, params=params).json()

Error Handling

Error	Cause	Solution
`401 Unauthorized`	Invalid credentials	Check client_id/secret
`403 Forbidden`	Insufficient permissions	Contact Workhuman admin
`invalid_grant`	Wrong grant type	Use client_credentials

Resources

Next Steps

Proceed to workhuman-hello-world for your first recognition nomination.