Provisioning API · Internal testing only
Register a sequencer account
const url = 'https://api.builders.ac/api/provisioning/v1alpha1/provider-accounts';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"provider":"instantly","username":"outbound@northwind-labs.com","url":"https://northwind.sequencer.example","api_key":"sk-northwind-EXAMPLE-0000000000000000","password":"example-password-not-a-real-one","totp_secret":"JBSWY3DPEHPK3PXPEXAMPLE0","sequencer_workspace":"Northwind Outbound","external_id":"crm-8421"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.builders.ac/api/provisioning/v1alpha1/provider-accounts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "provider": "instantly", "username": "outbound@northwind-labs.com", "url": "https://northwind.sequencer.example", "api_key": "sk-northwind-EXAMPLE-0000000000000000", "password": "example-password-not-a-real-one", "totp_secret": "JBSWY3DPEHPK3PXPEXAMPLE0", "sequencer_workspace": "Northwind Outbound", "external_id": "crm-8421" }'Verifies the credentials with the sequencer, then stores them against the named workspace. Every provider needs api_key; bison also needs url. Plusvibe supports API-key-only registration, including accounts created with Google sign-in. Providers that expose several workspaces from one key have the others discovered and listed in sequencer_workspaces. Send the api_key as a SealedValue sealed to a platform encryption key whenever request logs or intermediaries are not trusted with plaintext. Synchronous: no Operation is returned.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.
Request Bodyrequired
Section titled “Request Bodyrequired”Every provider needs api_key; bison also needs url. A missing provider-specific field is rejected as validation_error naming that field.
object
The sequencer behind a provider account.
Optional legacy browser-login username. Plusvibe authentication uses api_key, including for accounts created with Google sign-in.
Required for bison, whose API lives at a per-customer base URL; must be a public https or http URL. Rejected for every other provider.
A plaintext secret. Prefer SealedValue when request logs or intermediaries are not trusted with plaintext.
object
An ASCII-armored age v1 file. Response values are sealed to the API Key used for the request; request values are sealed to a recipient published by GET /encryption-keys.
A plaintext secret. Prefer SealedValue when request logs or intermediaries are not trusted with plaintext.
object
An ASCII-armored age v1 file. Response values are sealed to the API Key used for the request; request values are sealed to a recipient published by GET /encryption-keys.
A plaintext secret. Prefer SealedValue when request logs or intermediaries are not trusted with plaintext.
object
An ASCII-armored age v1 file. Response values are sealed to the API Key used for the request; request values are sealed to a recipient published by GET /encryption-keys.
The workspace at the sequencer the api_key belongs to. When omitted, the sequencer decides: if the key reaches exactly one workspace, that name is adopted; if it reaches several (bison, plusvibe), the request is refused as validation_error on this field, listing the names to choose from; Default is stored only when the sequencer reports no workspace at all. Providers that expose several workspaces from one key have the rest discovered on registration.
Your id for this registration. Opaque, case-sensitive, unique per Account within the provider-account resource type; set once. U+0000 is rejected when present.
Responses
Section titled “Responses”Provider account registered. Exact idempotent replays return this stored response without registering again.
object
Canonical lowercase TypeID.
The sequencer behind a provider account.
The login the upload worker signs in with; null when the sequencer authenticates by key alone.
The per-customer base URL, for providers that have one.
Workspace names known at the sequencer: the one registered plus any discovered from the key. PUT /domains/{dom}/sequencer takes one of these.
The outcome of the last credential check with the sequencer; null when the account has never been checked.
When the credentials were last verified with the sequencer.
Opaque and case-sensitive; unique per owning Account within the provider-account resource type.
Example
{ "id": "pra_01jsdqrf91f949ybjwh90xde9g", "object": "provider_account", "provider": "instantly", "username": "outbound@northwind-labs.com", "url": "https://northwind.sequencer.example", "sequencer_workspaces": [ "Northwind Outbound", "Northwind EU" ], "validation_status": "valid", "validated_at": "2026-04-16T11:02:37Z", "external_id": "crm-8421", "created_at": "2026-04-15T09:15:04Z", "updated_at": "2026-04-16T11:02:37Z"}Headers
Section titled “Headers”Canonical URL of the provider account.
Present with value true only when this is a stored replay.
The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Idempotency key required. The example shows idempotency_key_required.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_key_required", "title": "Idempotency key required", "status": 400, "detail": "This request requires a valid Idempotency-Key header.", "code": "idempotency_key_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required", "title": "Authentication required", "status": 401, "detail": "Provide an active Provisioning API Key as a Bearer token.", "code": "authentication_required", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive", "title": "Account inactive", "status": 403, "detail": "This account is inactive.", "code": "account_inactive", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
The owning Account already uses external_id, or an identical idempotent request is still running.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
External ID already in use
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/external_id_conflict", "title": "External ID already in use", "status": 409, "detail": "Choose a different external_id, or retrieve the existing resource using this external_id.", "code": "external_id_conflict", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Request already in progress
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_in_progress", "title": "Request already in progress", "status": 409, "detail": "A request using this idempotency key is still in progress.", "code": "idempotency_in_progress", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Either the request body is invalid (validation_error, with errors by field), a sealed value could not be opened (invalid_sealed_value), or the sequencer refused the credentials (provider_credentials_invalid, with validation naming the checks that failed). Nothing was stored.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
What the sequencer said, with nothing secret in it.
object
A sentence a person can act on.
object
Workspace names the key can reach, when the sequencer listed them; helps correct a wrong sequencer_workspace.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
Provider credentials rejected
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/provider_credentials_invalid", "title": "Provider credentials rejected", "status": 422, "detail": "The sequencer rejected these credentials; `validation` lists the checks that failed. Correct them and retry with a new Idempotency-Key.", "code": "provider_credentials_invalid", "retryable": false, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "validation": { "category": "invalid_credentials", "message": "The sequencer rejected the API Key.", "checks": [ { "key": "api_key", "status": "passed", "category": "invalid_credentials", "message": "The sequencer did not accept this key." } ], "sequencer_workspaces": [ "Northwind Outbound", "Northwind EU" ] }}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
Rate limit exceeded. The example shows rate_limit_exceeded.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Example
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Too many requests were made for this policy.", "code": "rate_limit_exceeded", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3", "retry_after": "2026-04-15T09:16:04Z"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.
The sequencer could not be reached to verify the credentials (provider_unreachable), or platform encryption keys are unavailable (encryption_keys_unavailable). Nothing was stored; retry later with a new Idempotency-Key.
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
object
Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.
object
Examples
Provider unreachable
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/provider_unreachable", "title": "Provider unreachable", "status": 503, "detail": "The sequencer could not be reached to verify these credentials. Nothing was stored; retry later.", "code": "provider_unreachable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Encryption keys unavailable
{ "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/encryption_keys_unavailable", "title": "Encryption keys unavailable", "status": 503, "detail": "Encryption key discovery is temporarily unavailable. Retry later.", "code": "encryption_keys_unavailable", "retryable": true, "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"}Headers
Section titled “Headers”The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.