Partner provisioning

Partner provisioning uses the machine API namespace /api/partner/v1 and a long-lived ykp_ bearer key. A key can create customer organizations only for its own partner platform and only while its provisioning grant, platform, template, and quota permit it.

POST /api/partner/v1/organizations

Creates one customer organization and starts its onboarding sequence. Returns 202 Accepted because organization creation commits before the remaining onboarding steps finish.

Every request must include:

Authorization: Bearer ykp_00000000-0000-4000-8000-000000000001.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Idempotency-Key: customer-create-8412
Content-Type: application/json

The credential above is an obviously fake, structurally valid example.

Idempotency-Key must contain 1–128 letters, numbers, dots, underscores, colons, or hyphens. It is scoped to the authenticated ykp_ key. The same text used under a different key is an independent claim; rotating a key therefore changes retry identity.

{
  "clientName": "Example Customer",
  "clientSegment": "example",
  "directLoginDisabled": true,
  "ownerEmail": "[email protected]",
  "ownerName": "Example Owner",
  "domainName": "General"
}

Reuse a key only with the byte-equivalent logical request. A different validated body returns 409 IDEMPOTENCY_KEY_REUSED.

Replay behavior

A completed retry within seven days returns 202, the stored provisioning outcome, and:

Idempotency-Replayed: true

It does not create another organization, follower record, onboarding run, or quota spend. If the original request is still running, the duplicate returns 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 2. An outcome that may have crossed the organization commit boundary but could not be recorded returns 409 IDEMPOTENCY_OUTCOME_UNKNOWN; do not retry it blindly.

Claims expire seven days after creation. The first request after expiry reclaims the key inline and executes as a fresh request; a bounded background sweep physically removes expired rows that are never retried.

Invitation credential

An original response may contain owner.invitation, a single-use activation link. It remains show-once credential material and is never stored in the idempotency record. The stored replay copy replaces that field with null; consequently a replay is identical to the original except when the original carried this invitation. Persist and deliver the original link securely if direct login is enabled.

Malformed headers and bodies are rejected before a claim is created. Named provisioning refusals that occur before organization creation release their claim, so correcting the request and retrying the key is allowed. Unknown failures after execution may have begun are retained as indeterminate instead of risking a duplicate organization.