Tohama Integration API
Partner-facing Integration API for the Tohama platform.
These endpoints let an external system create and read jobs, internships and seminars, and resolve the master data (locations, job categories, related universities) needed to build those payloads.
Authentication
Every request is authenticated with HMAC-SHA256 request signing — an API key, a timestamp, and a computed signature, sent as headers. There are no bearer tokens. See Request Signature in the guide for how to build the signature, including code samples.
Required on every request:
| Header | Description |
|---|---|
X-Api-Key | Your public API key. |
X-Timestamp | Current time in epoch milliseconds; must be within ±5 minutes of server time. |
X-Signature | Hex HMAC-SHA256 over `${timestamp}:${sha256(rawBody)}` keyed by your secret key. |
Optionally, X-Service-Lang (e.g. en, ja) selects the language used to
localize names in responses; it falls back to Accept-Language, then the
platform default.
Base URLs
Endpoints are served through the Azure API Gateway, with one base per
service: <gateway-base>/<service>/v1/external.
| Environment | Gateway base |
|---|---|
| Kenya production | https://ke-tohama-api-gateway.azure-api.net |
The <service> segment is one of jobs, seminars, universities, commons.
Each operation also documents which service it belongs to.
Conventions
- Request/response bodies are JSON (
Content-Type: application/json). - Dates are accepted as ISO 8601 (e.g.
2026-04-01) and stored asYYYY-MM-DD. - Times are 24-hour
HH:mmstrings. - Monetary / count fields are sent as plain numbers (e.g.
500000), never as formatted strings. - Unknown fields are rejected with a
VALIDATION_ERROR. - Company scope is always derived from your API key — you never send a company id, and you can only see and create resources for your own company.
- Every response includes a
requestId(echoed in theX-Request-Idheader); quote it when contacting support.
Authentication
- API Key: TohamaSignature
HMAC-SHA256 request signing. Every request must carry three headers:
X-Api-Key— your public API key.X-Timestamp— current Unix time in milliseconds (within ±5 min of server time).X-Signature— hex HMAC-SHA256 of`${timestamp}:${SHA256(rawBody)}`, keyed bySHA256(secretKey)(the hashed secret key).
For GET requests (no body) hash the empty string "". There is no
unsigned access. See the Request Signature guide for the full algorithm
and code samples.
OpenAPI can only attach one header to a security scheme, so only
X-Api-Keyis shown in the "Authorization" box. You must still sendX-TimestampandX-Signature— they are listed under each endpoint's parameters.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-Api-Key |
Contact Tohama API Support: api-support@tohama.com
License Apache 2.0