Authentication

builders.ac uses one credential pair across its HTTP APIs. Create it once, then send the API Key as the bearer token to Mailbox v1beta1, Deliverability v1alpha1, or Provisioning v1alpha1.

Provisioning is for internal testing only

The credential works with Provisioning, but the Provisioning API is not supported yet. It is available for internal testing only and must not be used for production workflows.

One credential, three APIs

Surface	Status	Base URL	API Secret needed?
Mailbox API	Beta	https://api.builders.ac/api/mailbox/v1beta1	No
Deliverability API	Alpha / unstable	https://api.builders.ac/api/deliverability/v1alpha1	No
Provisioning API	Internal testing only	https://api.builders.ac/api/provisioning/v1alpha1	Only locally for sealed values and proof challenges

The credential has two related values:

Value	Looks like	Use
API Key	age1…	Bearer token sent on every API request
API Secret	AGE-SECRET-KEY-1…	Client-side age identity for Provisioning sealed values and destructive-action proofs

The API Secret is not a second request credential. Mailbox and Deliverability never need it, and it never crosses the wire.

Create a credential

Open the API credentials page, create a credential, and download the key file when it is shown. The browser generates the pair and the server stores only a hash of the API Key. Neither raw value can be recovered later.

The API Secret is shown once

If you lose the downloaded secret, revoke the credential and create a replacement. Hold two active credentials while rotating so requests do not need to stop.

Authenticate a request

Send the API Key, not the API Secret:

Authorization: Bearer age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For example:

curl https://api.builders.ac/api/deliverability/v1alpha1/summary \
-H "Authorization: Bearer $BUILDERS_API_KEY"

A missing, malformed, revoked, or unknown key returns 401. Resources outside the credential’s account are constrained at the data query and normally return 404 rather than revealing that another account owns them.

Migrating the legacy Mailbox credential

The legacy Mailbox v1alpha1 authentication method is retiring. It accepts Vibe sk_live_… Mailbox keys at:

https://api.builders.ac/api/mailbox/v1alpha1

Do not create new integrations on that surface. Existing Microsoft Graph and Mailbox API clients should migrate as follows:

1. Create a shared age1… credential from the API credentials page.
2. Replace the bearer value with the new API Key.
3. Change the builders.ac Mailbox base from v1alpha1 to v1beta1:

   https://api.builders.ac/api/mailbox/v1beta1

4. Keep the upstream Microsoft Graph suffix unchanged: /azure/v1.0.

No retirement date is being announced here. Migration is recommended now so the legacy credential can be removed later without interrupting your integration.

Keep credentials safe

• Store the API Key and downloaded API Secret in a secret manager, not source control.
• Give each deployed integration its own credential so it can be revoked independently.
• Never send the API Secret in Authorization, a request body, a query string, or a support message.
• Revoke a credential immediately if either half may have been exposed.

Choose a surface

• Send or read mail from an existing Microsoft 365 mailbox → Mailbox API.
• Read traffic, bounce, ESP, and domain-check analytics → Deliverability API.
• Internally test workspace, domain, persona, and inbox provisioning → Provisioning API.
• Use Provisioning tools from a compatible AI client → MCP.