Base URL:
https://api.airmason.com/partner-api/v1
All requests and responses are JSON (Content-Type: application/json). All timestamps are ISO 8601 in UTC.
Authentication
The API uses two credentials with a deliberate split of responsibility:
Credential | Header | Lifetime | Used for |
Partner API key |
| Long-lived | Account-level actions: creating, listing, deactivating and reactivating organizations, minting access tokens |
Organization access token |
| 1 hour | Everything inside a single organization: employees, groups, handbooks, settings, SSO, webhooks |
Your partner key can never act directly on an organization's data, it can only mint a short-lived token scoped to one organization. This keeps the blast radius of a leaked key small.
Partner API key
Your key is issued by AirMason during onboarding and shown once. It is prefixed pk_ and is never stored on our side, so we cannot recover it: if it is lost, we issue a new one and revoke the old one.
GET /organizations
Authorization: ApiKey pk_live_4kR9…
IP allowlist
You can restrict your partner key to a set of IP addresses or CIDR ranges. Requests from outside the allowlist are rejected with 403 ip_not_allowed before any other processing. An empty allowlist means no IP restriction.
Organization access tokens
Exchange your partner key for a token scoped to one organization:
POST /oauth/token
Authorization: ApiKey pk_live_4kR9…
{ "organization_id": "ext:acme-eu" }
{
"access_token": "8fJ2k…",
"token_type": "Bearer",
"expires_in": 3600
}Then call organization endpoints with the token and the X-Org-Id header. The header must match the organization the token was minted for.
A mismatch returns 403 org_id_mismatch.
GET /organizations/ext:acme-eu/employees
Authorization: Bearer 8fJ2k…
X-Org-Id: ext:acme-eu
Tokens expire after one hour and refreshing is done by simply requesting a new one. Tokens are only issued for organizations that belong to your partner account (403 org_not_owned_by_partner otherwise).
Identifying organizations: AirMason IDs and your own IDs
Every organization has an AirMason id (a UUID) and an optional externalId (your own identifier for that customer), set when you create the org (or later via update). externalId must be unique across your account.
Anywhere the API takes an organization reference (a path segment, the X-Org-Id header, or the organization_id field of a token request) you can pass either form:
Form | Example |
AirMason ID |
|
Your ID, prefixed with |
|
Responses always return both id and externalId, so you can use whichever is convenient and never have to store ours.
The same convention applies to employees: reference an employee by their AirMason id or by ext:<employeeId>, where employeeId is the identifier you supplied when creating them (typically their ID in your HR system).
Conventions
Pagination
List endpoints accept limit (default 25, max 500) and offset (default 0), and return a pagination object:
{
"data": [ … ],
"pagination": { "limit": 25, "offset": 0, "total": 137 }
}
Quick start
# 1. Create an organization
curl -X POST https://api.airmason.com/partner-api/v1/organizations \
-H "Authorization: ApiKey pk_live_4kR9…" \
-H "Content-Type: application/json" \
-d '{"name":"Acme Corp","externalId":"acme-eu","orgType":"lite",
"ownerContact":{"firstName":"Jane","lastName":"Doe","email":"jane@acme.com"}}'
# 2. Get an access token for it
curl -X POST https://api.airmason.com/partner-api/v1/oauth/token \
-H "Authorization: ApiKey pk_live_4kR9…" \
-H "Content-Type: application/json" \
-d '{"organization_id":"ext:acme-eu"}'
# 3. Add an employee
curl -X POST https://api.airmason.com/partner-api/v1/organizations/ext:acme-eu/employees \
-H "Authorization: Bearer 8fJ2k…" -H "X-Org-Id: ext:acme-eu" \
-H "Content-Type: application/json" \
-d '{"employeeId":"R-10482","firstName":"Sam","lastName":"Okafor","email":"sam.okafor@acme.com"}'
Partner API documentation:
Overview & Getting Started