Partner API

Provision and manage Amdahl workspaces for your customers from your own platform: workspace creation, member management, and act-as sessions

The Partner API is for design partners embedding Amdahl into their own product. With a partner API key you can provision a workspace for each of your customers, add their members, watch what you have provisioned, and mint a short-lived act-as session to operate inside one of those workspaces as a named human on your team.

A partner key is not a workspace API key. It authenticates only this surface (/api/partner/v1/*), reaches only the workspaces your partner org provisioned, and cannot call any tenant endpoint directly — tenant access always goes through an act-as session or a real member sign-in.

Partner orgs, their members, and their keys are set up by the Amdahl team. Ask your contact to create your partner org, add your team's accounts as partner members, and issue your key with the scopes you need.

Authentication and scopes

Send your key on every request, either header works:

code

X-API-Key: amdhl_ptnr_...
Authorization: Bearer amdhl_ptnr_...

Three scopes, granted per key:

Scope	Grants
`partner:read`	The read surface: your org, your provisioned workspaces, their detail
`partner:provision`	Creating workspaces and adding members to them
`partner:act_as`	Minting act-as sessions inside provisioned workspaces

A valid key that lacks a route's scope gets a 403 with code: "insufficient_partner_scope". A revoked, expired, or suspended-partner key gets the same 401 as an invalid one.

Every action names a human

The key is headless, so every write asks you to name the person on your team doing it — an account the Amdahl team registered as a partner member of your org:

provisioning names the new workspace's owner (owner_user_id),
member-adds and act-as name the actor (actor_user_id).

An id that is not a partner member is refused. This is what keeps the audit trail honest: every workspace your platform touches attributes to a real person, never to a credential.

Endpoints

`GET /api/partner/v1/me`

Your partner org, the scopes on the calling key, and headline counts.

`GET /api/partner/v1/workspaces`

Every workspace your org provisioned, newest first, with its business_id, name, and slug.

`POST /api/partner/v1/workspaces`

Provision a workspace. Requires partner:provision.

json

{
  "name": "Customer Co",
  "slug": "customer-co",
  "owner_user_id": "<a partner member's user id>"
}

slug is optional (one is generated from the name). The new workspace gets the same first-run setup a self-serve workspace gets — onboarding funnel, default data-filter rules, managed workflows, profile warming — and is linked to your org, which is what makes it reachable to your key from then on.

Refusals: 409 workspace_limit once your org's cap is reached (ask the Amdahl team to raise it), 409 slug_taken, 400 slug_reserved / slug_invalid, and 400 owner_not_partner_member.

`GET /api/partner/v1/workspaces/:businessId`

One provisioned workspace. A workspace your org did not provision returns the same 404 as one that does not exist.

`POST /api/partner/v1/workspaces/:businessId/members`

Add a member to a provisioned workspace. Requires partner:provision.

json

{
  "email": "[email protected]",
  "role": "member",
  "actor_user_id": "<a partner member's user id>"
}

If no Amdahl account exists for the email, one is created and the person is emailed a sign-in notice (sign-in is a six-digit emailed code — there is no password to set). role is member (default) or admin.

`POST /api/partner/v1/workspaces/:businessId/act-as`

Mint an act-as session. Requires partner:act_as.

json

{
  "actor_user_id": "<a partner member's user id>",
  "reason": "configure onboarding",
  "duration_minutes": 30
}

Returns a short-lived token (30 minutes by default, 120 max) that authenticates API calls against that one workspace as a Bearer credential. Inside the workspace the session is clamped to the admin role — it can configure and operate the workspace but never reaches owner-only surfaces (billing, ownership transfer, workspace deletion). Every request made under an act-as token is recorded to the platform audit trail against the named actor.

Suspension

If your partner org is suspended, every key stops authenticating and act-as minting refuses, immediately and reversibly. Existing workspaces and their members are untouched — only your programmatic reach pauses.