Public API

Overview#

AI Workforce OS exposes a REST API covering the same functionality as the web application, with API key and OAuth-based authentication, an event-driven webhook system, and official SDKs in TypeScript, JavaScript, and Python.

Purpose#

Get a developer from "I need to integrate with AI Workforce OS" to a working authenticated API call.

Prerequisites#

• A System Administrator to issue you an API key or register an OAuth client.
• Familiarity with REST APIs and JSON.

Step-by-Step Instructions#

Authentication#

1. Ask a System Administrator to issue an API key for server-to-server integrations, or register an OAuth client for delegated/user-context access.
2. Include your credential on each request as required by the chosen auth method.
3. Review the interactive Swagger UI (served at /docs on your API instance) for the full endpoint reference and request/response schemas.

API keys and OAuth#

1. Manage issued API keys and API clients under Developer → API Keys / OAuth Clients in the web app.
2. Scope tokens appropriately — issue the narrowest access an integration actually needs.
3. Review API usage/logs for a given key under Developer → Logs.

Webhooks#

1. Go to Developer → Webhooks and create a subscription for the event(s) you care about.
2. Provide an HTTPS endpoint you control to receive delivery.
3. Verify incoming webhook payloads using the HMAC signature included with each delivery.
4. Review delivery history/logs for a subscription to confirm events are being received.

Using an official SDK#

// TypeScript / JavaScript
import { WfosClient } from "@ai-workforce-os/sdk";
const client = new WfosClient({ apiKey: process.env.WFOS_API_KEY });
const employees = await client.employees.list();

1. Install the SDK for your language: TypeScript, JavaScript (Node 18+), or Python (wfos_sdk).
2. Initialize the client with your API key or OAuth token.
3. Call the same resources exposed by the REST API (employees, leave, recruitment jobs, and more) through typed/idiomatic methods.

Screens Involved#

Expected Results#

A successful authenticated API call returns real data from your tenant, and a subscribed webhook delivers a signed payload to your endpoint when the relevant event occurs.

Not Available in This Release#

Common Mistakes#

• Not verifying the webhook HMAC signature, which leaves your endpoint open to spoofed delivery attempts.
• Issuing an overly broad API key/OAuth scope for a narrow integration.
• Hardcoding API keys in client-side code instead of a server-side integration.

Troubleshooting#

My API requests return 401 Unauthorized.#

Confirm your API key or OAuth token is valid and has not been revoked, and that you are sending it in the expected header format documented in the Swagger UI.

A webhook subscription is not receiving events.#

Confirm your endpoint is publicly reachable over HTTPS and returns a success response quickly. Check the subscription’s delivery log for failure details.

Related Pages#

FAQ#

Best Practices#

• Always verify webhook signatures before trusting a payload.
• Rotate API keys periodically and immediately after any suspected exposure.
• Use the narrowest OAuth scope an integration needs.