Skip to main content

Automate Spaces configuration using the Retool API

Learn how to programmatically configure Spaces using the Retool API.

Available on:Enterprise plan

The Retool API is currently in beta. Reach out to your Retool account team to get access.

If you need to configure many Spaces, you may want to programmatically configure them with the Retool API, rather than manually create and configure every Space. You can use the commands in this guide within Retool apps, workflows, or other scripts to streamline Spaces configuration.


The Retool API is available to cloud organizations and self-hosted organizations running v3.18 or later. API users must generate access tokens to authenticate. This guide assumes you have an access token with Read and Write scopes for users, permissions, and Spaces.

1. Get existing spaces

From the Admin Space, use the following command to retrieve all existing Spaces.

curl -X GET https://{ADMIN_SPACE_DOMAIN}/api/v2/spaces -H 'Authorization: Bearer $BEARER_TOKEN'

2. Edit theme

From the child Space, update the theme.

curl -X PUT https://{CHILD_SPACE_DOMAIN}/api/v2/app_themes -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Default theme", "theme": {"info": "hsl(208, 70%, 55%)", "canvas": "#FFFFFF", "danger": "#CA483F", "primary": "#128747", "success": "#128747", "warning": "#D17823", "tertiary": "#034822", "textDark": "#262626", "highlight": "#f6e5c4","secondary": "#d7eae0", "textLight": "#FFFFFF", "borderRadius": "4px", "surfacePrimary": "#FFFFFF", "surfaceSecondary": "#F9F9F9"}}'

3. Edit SSO configuration

From the child Space, update the SSO configuration. See the Retool API and SSO documentation for more detail on SSO fields.

curl -X POST https://{CHILD_SPACE_DOMAIN}/api/v2/sso/config -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data
'{"data": {"config_type": "google", "google_client_id": "GOOGLE_CLIENT_ID", "google_client_secret": "GOOGLE_SECRET", "disable_email_password_login": false}}'

4. Create a Source Control configuration

From the child Space, create a Source Control configuration.

curl -X POST https://{CHILD_SPACE_DOMAIN}/api/v2/source_control/config -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data {"config": {"config": {"type": "App", "app_id": "app_id", "installation_id": "installation_id", "private_key": PRIVATE_KEY, "url": "string", "enterprise_api_url": "string"}, "provider": "GitHub", "org": "github_organization", "repo": "github_repo", "default_branch": "main"}}

5. Create additional Spaces

You can generate a new Space with settings automatically copied over from an existing Space. Set copy_sso_settings and copy_branding_and_themes_settings to true when you create the Space.

curl -X POST https://{ADMIN_SPACE_DOMAIN}/api/v2/spaces -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Finance", "domain": "", "options": {"copy_sso_settings": true, "copy_branding_and_themes_settings": true}}'