Integrations

Supabase Integration

Connect Astrolabe to Supabase for project and database management

Supabase Integration

Connect your Supabase account to Astrolabe for native desktop access to projects, organizations, and API key management.

Features

OAuth Authentication with PKCE: Most secure authentication flow
Project Management: View and create Supabase projects
Organization Access: Manage projects across organizations
API Key Management: Securely retrieve project API keys
Token Refresh: Automatic token renewal for uninterrupted access

Prerequisites

Astrolabe v0.1.12 or later
Active Supabase account
macOS 15.0 or later

Setup

Option 1: OAuth (Recommended)

Supabase OAuth uses PKCE (Proof Key for Code Exchange) for enhanced security.

Open Settings

Launch Astrolabe and navigate to Settings → Integrations.

Click "Link your Supabase account"

Find the Supabase section (marked with 🔐 OAuth Ready and OAuth + PKCE badges) and click the button.

Authorize in Browser

Your browser opens to Supabase's authorization page at api.supabase.com/v1/oauth/authorize.

Permissions:

Access to your organizations
Ability to create and manage projects
Read project API keys

Return to Astrolabe

After authorizing, you're redirected to astrolabe://oauth/callback/supabase. Your token and refresh token are securely saved.

Start Using Supabase

Link projects and manage your Supabase resources from Astrolabe.

Option 2: Personal Access Token

Generate Token

Go to supabase.com/dashboard/account/tokens
Click "Generate new token"
Give it a name like "Astrolabe Desktop"
Copy the token immediately (shown only once)

Add to Astrolabe

Open Settings → Integrations
Find the Supabase section
Paste your token in the Personal Access Token field

Usage

Linking a Project

Open Project

Navigate to your project in Astrolabe.

Click Supabase Button

In Service Integrations, click the Supabase button.

Select Organization & Project

First, select your organization from the dropdown
Then, select the Supabase project to link

Confirm

Click "Link Project" to establish the connection.

Creating a New Supabase Project

Go to Quick Actions

From any project page, find the Supabase integration section.

Click "Create Project"

Choose "Create new Supabase project".

Fill Details

Enter:

Project name
Organization (must be pre-selected)
Database password
Region (e.g., us-east-1)

Create

Click "Create Project" and wait for provisioning (may take 1-2 minutes).

Retrieving API Keys

Select Linked Project

Ensure your project is linked to a Supabase project.

View Keys Section

Navigate to the API Keys section in project details.

Copy Keys

Astrolabe displays:

Anon public key (for client-side use)
Service role key (for server-side use, handle with care)

OAuth Token Refresh

Supabase OAuth tokens expire periodically. Astrolabe automatically refreshes them:

Expiration Detection: Checks expiresAt timestamp
Refresh Request: Calls Supabase token refresh endpoint
Update Storage: Saves new access token and refresh token
Seamless UX: No user intervention required

If refresh fails, you'll be prompted to re-authenticate.

Organization Management

For organizations:

List organizations you're a member of
Filter projects by organization
Create projects in specific organizations
Permission-based access based on your org role

API Capabilities

Astrolabe uses Supabase Management API v1:

OAuth Token Exchange: POST /v1/oauth/token (with PKCE)
Refresh Token: POST /v1/oauth/token (grant_type: refresh_token)
List Organizations: GET /v1/organizations
List Projects: GET /v1/projects
Get Project: GET /v1/projects/:ref
Get API Keys: GET /v1/projects/:ref/api-keys
Create Project: POST /v1/projects

All requests use:

Authorization: Bearer {token}
Accept: application/json
Basic auth for token exchange (client_id:client_secret)

Troubleshooting

OAuth Authorization Fails

Issue: Redirect doesn't complete.

Solution:

Ensure Astrolabe is running
Check redirect URI is astrolabe://oauth/callback/supabase
Try re-authenticating

Token Expired Error

Issue: API calls fail with 401 Unauthorized.

Solution:

Astrolabe should auto-refresh tokens
If auto-refresh fails, re-authenticate manually
Check refresh token is valid

Organizations Not Loading

Issue: Organization dropdown is empty.

Solution:

Verify you're a member of at least one organization
Re-authenticate to refresh permissions
Check token scopes

Project Creation Fails

Issue: "Failed to create project" error.

Solution:

Ensure you have permission in the selected organization
Check database password meets requirements (min 8 chars)
Verify organization has available project slots

Security

PKCE Flow: Code challenge/verifier prevents authorization code interception
OAuth Tokens: Stored encrypted in Tauri plugin-store
Refresh Tokens: Stored locally in localStorage with expiration tracking
Basic Auth: Client credentials sent via Authorization header (not in body)
No Token Exposure: Tokens never logged or transmitted to third parties

Advanced: Manual Token Management

If you prefer manual control:

// Refresh token manually (usually automatic)
await invoke("cmd_supabase_refresh_token", {
  refreshToken: "your_refresh_token",
  clientId: "your_client_id",
  clientSecret: "your_client_secret"
});

Support

Need help with Supabase integration?

Netlify Integration

Connect Astrolabe to Netlify for deployment monitoring and site management

Frequently Asked Questions

Common questions and answers about Astrolabe