Skip to main content
Lumos supports Retool for both Retool Cloud and self-hosted (on-prem) instances. Self-hosted instances connect through the Lumos on-prem agent.

​
After this article

You’ll be able to connect Retool to Lumos to sync and manage users, roles, groups, and resource permissions, including provisioning and deprovisioning access to Retool apps, dashboards, and folders.

​
Capabilities

​
Required plan and roles

  • Retool plan: the Enterprise Plan is required. Full API access isn’t available on lower plans.
  • Retool role: an admin must create the access token from Settings → API.
  • Token scopes:
    • Users > Read / Users > Write (sync and manage user accounts)
    • Groups > Read / Groups > Write (sync and manage group membership)
    • Permissions > Read / Permissions > Write (sync and manage resource permissions)
    • Folders > Read (read folders)
    • Apps > Read (read applications)
    • Organizations > Read (read organization data)
  • Read-only option: for a read-only connection, select only the read scopes and don’t grant any write scopes. The write scopes above are required for Lumos provisioning and deprovisioning.

​
Read-only access vs provisioning

Is read-only possible? Yes. Retool’s access token scopes split into read and write pairs, and granting only the read scopes gives Lumos a sync-only connection. What read-only requires. An Enterprise-plan access token from Settings → API with only the Users > Read, Groups > Read, Permissions > Read, Folders > Read, Apps > Read, and Organizations > Read scopes, and none of the corresponding write scopes. Follow the steps below, omitting the write scopes when you create the token. What full provisioning requires. The same access token with the write scopes added: Users > Write, Groups > Write, and Permissions > Write. These are required for account creation, deprovisioning, and resource permission changes. Watch out for. The Enterprise plan is required either way, full API access isn’t available on lower plans. The token’s scopes decide the mode and there’s no separate read-only tile to pick, so choose the right scopes when you create the token in Retool.

​
Instructions

Phase 1: Generate an access token in Retool
  1. In Retool, go to Settings → API and click Create new.
  2. Enter a name and description for the token.
  3. Select the scopes listed in Required plan and roles above. Omit the write scopes for a read-only connection.
  4. Copy and save the token. It’s accessible only once.
  5. Note your Instance URL, including the protocol (for example https://example.retool.com for Retool Cloud, or your self-hosted domain).
Phase 2: Connect in Lumos
  1. Find the Retool card in your Lumos integrations. Reconnect an existing card or add a new one.
  2. Complete the on-prem agent setup (Docker Image Setup or Windows Setup, per the Lumos Developer Docs), then click Continue.
  3. Enter the Access Token and Instance URL.
  4. Click Connect.

​
API Endpoints Used

​
Troubleshooting

Users aren’t syncing. Verify the token can read user data and hasn’t been revoked or expired. Make sure users have email addresses and are active. Confirm your Retool plan includes full API access. Review the Lumos integration logs. API token authentication failures. Verify the complete token was pasted and hasn’t been deleted or revoked. Check it was created by an admin account and that the organization is active. Confirm the Instance URL is correct, including https://. Generate a new token if needed. Groups aren’t appearing. Verify the token can read group data and that groups exist with at least one member. Applications aren’t syncing. Verify the token can read application data and that apps aren’t archived. Only app metadata syncs. App code and queries are excluded by design. Sync crashes on folder validation (self-hosted). Older connector versions failed when Retool introduced the agent folder type (seen on Retool 0.170.0). This is fixed. If you still see it, trigger a fresh sync.