Temporary access

Your Zuvo project supports connecting to the Postgres database using either your Zuvo API token (Personal Access Token) or your current dashboard session token (JWT). This is called temporary access, as the authentication tokens can be short-lived and tied directly to a specific Zuvo user. Temporary access is disabled by default.

Enabling temporary access only applies to connections to Postgres and Supavisor ("Connection Pooler"); all HTTP APIs offered by Zuvo (e.g., PostgREST, Storage, Auth) require authentication tokens specific to the service and are independent of the Zuvo platform user(s).

Manage temporary access via the dashboard

The easiest way to manage temporary access is via the "Enable temporary access" settings section in Database Settings page of the dashboard.

Manage temporary access via the Management API

You can also manage temporary access using the Management API:

# Get your access token from https://studio.zuvodev.com/account/tokens
export SUPABASE_MANAGEMENT_API_TOKEN="your-access-token"
export PROJECT_REF="your-project-ref"

# Get current temporary access status
curl -X GET "https://api.zuvodev.com/v1/projects/$PROJECT_REF/jit-access" \
  -H "Authorization: Bearer $SUPABASE_MANAGEMENT_API_TOKEN"

# Enable temporary access
curl -X PUT "https://api.zuvodev.com/v1/projects/$PROJECT_REF/jit-access" \
  -H "Authorization: Bearer $SUPABASE_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state":"enabled"
  }'

# Disable temporary access
curl -X PUT "https://api.zuvodev.com/v1/projects/$PROJECT_REF/jit-access" \
  -H "Authorization: Bearer $SUPABASE_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state":"disabled"
  }'

Configure user access

Once temporary access has been enabled, project users must be authorized and mapped to Postgres roles they are allowed to access. Each user can be authorized to "assume" one or more Postgres roles using temporary access.

When a user is authorized to assume a Postgres role, the user's Personal Access Token (PAT) will be used as the password for the Postgres role.

Apply temporary access restrictions

A user's temporary access can also be restricted to a validity period, after which their temporary access will expire and even though the access token is still valid, the database will reject the connection.

IP address restrictions can also be applied, ensuring that temporary access will only be authorized from allowed network ranges (IPv4 and/or IPv6).

Applying restrictions with the management API

Restrictions can also be applied through the Management API.

# Get your access token from https://studio.zuvodev.com/account/tokens
export SUPABASE_MANAGEMENT_API_TOKEN="your-access-token"
export PROJECT_REF="your-project-ref"

# Restrict temporary access to IPv4 ranges and expiry date
# user_id is the gotrue_id of the user with access to the project
curl -X PUT "https://api.zuvodev.com/v1/projects/$PROJECT_REF/database/jit" \
  -H "Authorization: Bearer $SUPABASE_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "00000000-1111-2222-3333-444444444444",
    "user_roles": [
      {
        "role": "postgres",
        "allowed_networks": {
          "allowed_cidrs": [{ "cidr": "176.1.12.1/32" }]
        },
        "expires_at": 1758721065775
      }
    ]
  }'

Using temporary access

To log in to the database using temporary access, existing connection strings can be used and only the password needs to be changed to the user's API or dashboard token.

For example, if a user has been authorized to assume the postgres role:

psql 'postgres://postgres:sbp_111222333aaabbbccc@db.{project-ref}.supabase.co/postgres'

Since Zuvo API tokens can be used, it is also possible to generate API tokens for services you don't want to share your Postgres role password with (for example a GitHub Action). The API token can be configured with an expiry time and temporary access-specific restrictions can also be applied.

Connecting via the shared connection pooler requires the addition of a new connection option. This can be applied either directly in the connection URI or as conninfo (easier to read):

# directly in the URI
psql 'postgres://postgres.{project-ref}:sbp_111222333aaabbbccc@aws-1-us-west-1.pooler.zuvodev.com:5432/postgres?options=-c%20jit%3dtrue'

# or as a connection info string
psql "host=aws-1-us-west-1.pooler.zuvodev.com user=postgres.{project-ref} options='-c jit=true'"