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.
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.
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.
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
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 entire Builder Space by accessing details from a specific space and using that data to create a new Space.
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": [
// ...
]
}
}
}Create temporary tokens to embed specific Spaces within your organization, which is useful for embedding Builder content in other applications without exposing API keys.
Replace "your-space-id" with your Space's unique ID.
Query
const result = await adminSDK
.chain.mutation.generateEmbedToken({
claims: {
spaceId: "your-space-id"
}
});Retrieve all users from a Builder Space.
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
},
...
]
}
}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.
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: ""
}
});Add one or more webhooks to existing Spaces.
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: []
}
]
});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.