Partner API

Create your first customer Space with a partner tenant API key.

The Partner API lets your product publish and manage Spaces for your own customers. It uses the same base URL and publishing operations as the Spacefast API. A partner tenant keeps your customers, credentials, configuration, and usage separate from other partners.

Partner access requires account setup. Your account has a live tenant and a linked test tenant. Start with the test tenant ID and a tenant API key from your partner account.

Read your tenant

Set SPACEFAST_API_KEY to the test tenant’s API key and SPACEFAST_TENANT_ID to its tenant ID. Keep the API key on your server.

curl --fail-with-body -sS \
  "https://api.spacefast.com/v1/tenants/$SPACEFAST_TENANT_ID" \
  -H "Authorization: Bearer $SPACEFAST_API_KEY"

Check that data.mode is test and data.status is active. The response also includes systemSpaceId, manifestStatus, presentation, and domain setup instructions.

The signed-in team’s partner account is available through GET /v1/teams/{teamId}/partner. That operation requires a team member session. Server integrations use their tenant API key.

Create a customer Space

Choose a stable customer ID from your own system. Use lowercase ASCII IDs such as customer_123 throughout the integration.

curl --fail-with-body -sS https://api.spacefast.com/v1/spaces \
  -H "Authorization: Bearer $SPACEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"title":"Customer site","principal":{"type":"external","id":"customer_123"}}'

Set IDEMPOTENCY_KEY to a fresh UUID for each new Space and reuse it only to retry that request. See idempotency.

Save data.space.id. Spacefast creates the customer principal when it first owns a resource. There is no separate customer registration call.

Publish content to that Space with the publish flow or sf publish --space. Test tenants simulate provisioning. A test result does not prove that a live hostname or certificate works.

Use the partner SDK

Use the partner client to retain partner-specific request and response fields.

import { createSpacefastPartnerClient } from "@spacefast/sdk/partner";

const key = process.env.SPACEFAST_API_KEY;
const client = createSpacefastPartnerClient({
  baseUrl: "https://api.spacefast.com",
  apiKey: key,
});

const customers = await client.get("/v1/principals", {
  query: { limit: 20 },
});

Use a separate client and query cache for each tenant and customer identity. A tenant API key grants management access. Give customer applications a partner JWT scoped to that customer.

Rotate a tenant API key

Create a replacement with POST /v1/tenants/{tenantId}/api-keys. The body accepts name, optional permissions, expiresAt, notBefore, ipAllowlist, and metadata. Omitted permissions grant partner administration. Explicit permissions narrow the grant.

Save the returned secret, update your integration, and verify a request with the replacement. Then revoke the old key with DELETE /v1/tenants/{tenantId}/api-keys/{apiKeyId}. Revocation takes effect on subsequent requests. GET /v1/tenants/{tenantId}/api-keys returns masked previews, never existing secrets.

Continue the integration

• Issue customer JWTs for customer-scoped access.
• Configure your partner account through a system Space.
• Manage customers and usage for plans, suspension, and billing records.
• Promote to live after the sandbox checks pass.

The Partner API reference lists request schemas and permissions. Download its OpenAPI document from https://api.spacefast.com/openapi.partner.json. The shared error, pagination, idempotency, and operation contracts also apply.