Complete onboarding if both steps are done

curl --request POST \
  --url https://billing.basaltic.sh/v1/onboarding/activate \
  --header 'Authorization: <api-key>'

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://billing.basaltic.sh/v1/onboarding/activate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.basaltic.sh/v1/onboarding/activate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.basaltic.sh/v1/onboarding/activate"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.basaltic.sh/v1/onboarding/activate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "pending": true,
  "phone_verified": true,
  "payment_method_added": false,
  "completed": false
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Billing

Complete onboarding if both steps are done

Re-evaluates the two onboarding conditions — a verified phone on the organization’s owner and at least one payment method — and activates the organization if both hold, then answers with the resulting state.

Idempotent, and safe for any member to call: it grants nothing the server has not verified itself, and an organization that is already active, or not yet ready, comes back unchanged.

It exists because the two steps complete in different services. Attaching a payment method activates from inside this service, but verifying a phone happens in iam, which cannot read these tables — so something has to re-check afterwards. A client that calls this whenever it sees a pending organization also makes an interrupted signup self-healing.

POST

onboarding

activate

Complete onboarding if both steps are done

curl --request POST \
  --url https://billing.basaltic.sh/v1/onboarding/activate \
  --header 'Authorization: <api-key>'

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://billing.basaltic.sh/v1/onboarding/activate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.basaltic.sh/v1/onboarding/activate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.basaltic.sh/v1/onboarding/activate"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.basaltic.sh/v1/onboarding/activate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "pending": true,
  "phone_verified": true,
  "payment_method_added": false,
  "completed": false
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

BASALTIC-HMAC-SHA256 request signing for service-account (access-key) auth. An AWS-SigV4-style scheme: an HMAC-SHA256 over a canonical request, keyed by a signing key derived from your secret access key. The basaltic CLI does this for you; the steps below are for a non-CLI client.

Headers you send

Authorization (this scheme) — format below.
X-Date: request time in UTC, compact ISO-8601 basic: YYYYMMDDTHHMMSSZ (e.g. 20240115T103000Z). Must be within 5 minutes of server time.
X-Nonce: random per-request value (e.g. 16+ bytes of hex). Required — it is what makes each signature unique so the server can reject replays. X-Date alone is not enough (one-second resolution; UNSIGNED-PAYLOAD never enters the canonical request).
X-Content-Sha256 (optional): lowercase-hex SHA-256 of the request body, to bind the exact bytes to the signature — the server re-hashes and rejects a mismatch. Omit it, and put the literal UNSIGNED-PAYLOAD in the body-hash slot, for an empty body or a streaming upload that shouldn't be buffered.

Authorization header format

Authorization: BASALTIC-HMAC-SHA256 Credential=<access_key_id>/<date>/<region>/<service>/basaltic_request, SignedHeaders=<h1>;<h2>, Signature=<hex>

<date>: YYYYMMDD (the day part of X-Date).
<region>: target region code (e.g. sa-saopaulo-1), or global for the region-agnostic (IAM) endpoints.
<service>: basaltic.
SignedHeaders: the covered header names, lowercased and sorted, joined by ; — at minimum host;x-date;x-nonce (all three required).
Signature: lowercase hex from step 4.
Note the , (comma + space) between the three Authorization parameters.

Step 1 — canonical request

Join these six lines with \n (LF):

<HTTP-METHOD>
<canonical-path>
<canonical-query>
<canonical-headers>
<signed-headers>
<body-hash>

canonical-path: the URL-escaped request path (e.g. /v1/compute/instances).
canonical-query: each query key and value URL-encoded, sorted by key then value, joined by &; empty string when there is no query.
canonical-headers: for each signed header, name:value (name lowercased, value trimmed), sorted by name, each followed by a trailing \n.
signed-headers: the same names, lowercased, sorted, joined by ;.
body-hash: lowercase-hex SHA-256 of the body, or the literal UNSIGNED-PAYLOAD.

Step 2 — string to sign

Join with \n:

BASALTIC-HMAC-SHA256
<date>T000000Z
<date>/<region>/<service>/basaltic_request
<hex SHA-256 of the canonical request>

The second line is the credential date at midnight — NOT the X-Date value — and the third is the credential scope without the access-key id.

Step 3 — derive the signing key (HMAC chain over your secret)

kDate    = HMAC-SHA256("BASALTIC" + <secret_access_key>, <date>)
kRegion  = HMAC-SHA256(kDate, <region>)
kService = HMAC-SHA256(kRegion, <service>)
kSigning = HMAC-SHA256(kService, "basaltic_request")

Step 4 — signature

Signature = lowercase_hex( HMAC-SHA256(kSigning, <string-to-sign>) )

Example (POST with a JSON body)

X-Date: 20240115T103000Z
X-Nonce: 7f3a9c2e1b84d056
X-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: BASALTIC-HMAC-SHA256 Credential=BCAK1234567890ABCDEF/20240115/global/basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature=a1b2c3d4e5f6...

Request validity

Valid for 5 minutes from the X-Date timestamp.
The signature must cover at least host, x-date, and x-nonce.
Mutating requests (POST/PUT/PATCH/DELETE) that present a signed nonce are anti-replay guarded for the drift window; omitting X-Nonce is rejected.

Rate limits

There is no global request budget: a limit applies only where an operation documents a 429 response, and each such endpoint counts its own fixed window. Everything else is bounded by quota, not by request rate.

Per-endpoint request limits

A few endpoints are limited in front of the handler, counted per caller — the authenticated principal when the request carries credentials, the client IP otherwise. On this API surface that is the public region catalogue, GET /v1/regions: it guards no secret, and the budget is there because the catalogue is unauthenticated and database-backed.

An operation that is limited says so by documenting a 429. These responses — 429 and 2xx — carry the budget, so a client can pace itself instead of discovering the ceiling by hitting it:

X-RateLimit-Limit — requests allowed per window on this endpoint. Authoritative: read it rather than hard-coding a number.
X-RateLimit-Remaining — requests left in the window (0 on a 429).
X-RateLimit-Reset — seconds until the window resets. A duration, not a timestamp, so it needs no clock agreement.
Retry-After — on a 429 only; seconds to wait. Never zero.

Over the limit the response is 429 with error code RATE_LIMITED. Honor Retry-After — retrying sooner is refused and extends the window, since the refused attempt is itself counted.

Service-level limits

Some resources meter the work itself rather than the request, and are documented on the operation. They return 429 with their own error code and no rate-limit headers, because the budget is not a per-endpoint window: sending email is capped per (account, identity) per second (EMAIL_RATE_LIMIT), and charge attempts are capped per invoice (INVOICE_PAYMENT_ATTEMPTS_EXHAUSTED).

Response

The onboarding state after the attempt.

Which of the onboarding steps an organization has completed. Both must be done before it leaves the pending status; until then every resource API refuses it with ORGANIZATION_ONBOARDING_REQUIRED.

organization_id

string<uuid>

required

Example:

"550e8400-e29b-41d4-a716-446655440000"

pending

boolean

required

Whether the organization is still onboarding. False for an organization that finished, and also for one created before the requirement existed.

Example:

true

phone_verified

boolean

required

Whether the organization's OWNER has a verified phone number.

Example:

true

payment_method_added

boolean

required

Example:

false

completed

boolean

required

Whether onboarding is done. Not simply the AND of the two steps — an organization suspended or terminated after onboarding also reads as completed, because there is nothing left for the user to do here.

Example:

false

Overview

Identity and account

Quota

Audit

Billing

Compute

Database

Registry

Network

Load balancer

DNS

Certificate

Storage

KMS

Secrets

Queue

Notifications

Email

Telemetry

Complete onboarding if both steps are done

Authorizations

Headers you send

Authorization header format

Step 1 — canonical request

Step 2 — string to sign

Step 3 — derive the signing key (HMAC chain over your secret)

Step 4 — signature

Example (POST with a JSON body)

Request validity

Rate limits

Per-endpoint request limits

Service-level limits

Response