Manage Spaces

Create, duplicate, or embed Builder Spaces using the Admin API. Use these operations to provision new environments, copy existing Spaces, or generate tokens for secure embedding.

Note that the Private API Key for an organization is different than the private key for a single Builder Space.

Create a Space

Duplicate a Space using either the source Space Private API Key or the parent root Organization Private Key. copySpace supports optional includeUsers and skipAssets flags.

This operation returns a newly generated private key for the duplicated Space. Store this key securely.

Framework

Query

const result = await adminSDK .chain.mutation.createSpace({ settings: { name: "Development Environment", description: "Space for development and testing" } });

Response

{ "data": { "createSpace": { "organization": { "name": "Dev Environment", "id": "...", "type": "space", ... }, "privateKey": { ... } } } }

When creating a Space, you can also directly add webhooks by adding a webhooks key and then following the same structure described within the Create a webhook section.

Copy a Space

Duplicate a Space using either the source Space Private API Key or the parent root Organization Private API Key. Supports optional includeUsers and skipAssets flags and returns the new Space ID and its Private API Key. Requires Organization Admin permissions

Framework

Query

const result = await adminSDK .chain.mutation.copySpace({ sourceSpaceId: "space-123", name: "My Duplicate Space", includeUsers: true, skipAssets: true }) .execute();

Response

{ "data": { "copySpace": { "newSpaceId": "generated-id", "privateKey": { "id": "bpk-generated", "key": "bpk-xyz...", "ownerId": "generated-id", "active": true, "name": "Auto generated" } } } }

Clone your space

Clone your entire Builder Space by accessing details from a specific space and using that data to create a new Space.

Framework

For example, the following code selects 10 Models from your Space, returning the id, kind, and name. Use this data when creating a new Space programatically.

Query

const result = await adminSDK .chain.mutation.downloadClone({ contentQuery: { limit: 10 } }) .execute();

Response

{ "data": { "downloadClone": { "models": [ // ... ] } } }

Generate an embed token

Create temporary tokens to embed specific Spaces within your organization, which is useful for embedding Builder content in other applications without exposing API keys.

Framework

Replace "your-space-id" with your Space's unique ID.

Query

const result = await adminSDK .chain.mutation.generateEmbedToken({ claims: { spaceId: "your-space-id" } });

Get users

Retrieve all users from a Builder Space.

Framework

To get all users from your Builder Space, use the following query.

Query

const response = await adminSDK .query({ users: { id: true, name: true, email: true, role: true, lastActive: true } });

Response

{ "data": { "users": [ { "id": "...", "name": "Elena Aguilar", "email": "elena@builder.io", "role": "admin", "lastActive": 1746049078845 }, ... ] } }

Configure SSO providers

To configure SSO providers through the Admin API, SSO must first be enabled for your space. For more details on SSO options, see SSO with your Identity Provider and Using Code Flow with SSO.

Framework

To set up a new SAML authentication provider within your space, use the following query.

const result = await adminSDK.chain.mutation.addSAMLProvider({ settings: { displayName: "Company SSO", idpEntityId: "https://sso.company.com/entityId", ssoURL: "https://sso.company.com/login", x509Cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", rpEntityId: "https://www.builder.io" } });

To set up an OIDC authentication provider within your space, use the following query.

const result = await adminSDK.chain.mutation.addOIDCProvider({ settings: { displayName: "Company SSO", clientId: "https://sso.company.com/entityId", issuer: "" } });

Create a webhook

Add one or more webhooks to existing Spaces.

Framework

const result = await adminSDK .chain.mutation.updateWebhooks({ webhooks: [ { url: "https://webhook1.example.com/content-update", disablePayload: false, customHeaders: [ { name: "Authorization", value: "Bearer token123" } ] }, { url: "https://webhook2.example.com/notify", disablePayload: true, customHeaders: [] } ] });

What's next

Continue to explore the Admin API documentation or use the GraphQL Explorer to try out these queries with your own Space and Organization. Then, visit the Admin API GraphQL Schema for more details on how to modify your queries.