Automate Spaces configuration using the Retool API
Learn how to programmatically configure Spaces using the Retool API.
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.
Requirements
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
To use Spaces with Source Control, ensure you migrate your apps to Toolscript.
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. When you create spaces programmatically, you also must set create_admin_user to true. This creates a default admin user with the email of the API key creator.
curl -X POST https://{ADMIN_SPACE_DOMAIN}/api/v2/spaces -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Finance", "domain": "finance.sample-org.dev", "options": {"copy_sso_settings": true, "copy_branding_and_themes_settings": true, "create_admin_user": true}}'