Supabase RLS Compatibility

KeyHippo is designed to work with Supabase’s existing Row Level Security (RLS) framework. This ensures that you can introduce API key authentication without disrupting your current security policies or requiring a complete overhaul of your existing setup.

​

Fundamental Principles

1. Non-Invasive Integration: KeyHippo extends RLS functionality without altering core Supabase behavior.
2. Dual Authentication Support: Policies can utilize both Supabase’s session-based auth and KeyHippo’s API key auth.
3. Familiar Syntax: KeyHippo functions are designed to feel natural alongside existing Supabase RLS expressions.

​

Compatibility with Existing Policies

​

Enhancing Current Policies

Existing RLS policies can be easily enhanced to include API key authentication. For example:

Original Supabase Policy:

CREATE POLICY "users can view own data"
ON public.profiles
FOR SELECT
USING (auth.uid() = user_id);

Enhanced Policy with KeyHippo:

CREATE POLICY "users can view own data"
ON public.profiles
FOR SELECT
USING (
  auth.uid() = user_id
  OR auth.keyhippo_check(user_id)
);

This enhancement allows access via both session authentication and API key, without changing the fundamental logic of the policy.

​

Preserving Policy Behavior

KeyHippo is designed to preserve the behavior of your existing policies when no API key is present. This means:

• Requests authenticated with Supabase sessions continue to work exactly as before.
• Unauthenticated requests behave the same way they did prior to KeyHippo integration.

​

KeyHippo-Specific Functions in RLS

KeyHippo introduces several functions that can be used within RLS policies:

1. auth.keyhippo_check(user_id UUID): Verifies if the request is authenticated with a valid API key for the given user.

2. keyhippo.key_uid(): Retrieves the user ID associated with the current API key.

3. keyhippo.get_api_key_metadata(user_id UUID): Fetches metadata about API keys, useful for more complex policy logic.

Example using KeyHippo-specific functions:

CREATE POLICY "premium_access"
ON public.premium_content
FOR SELECT
USING (
  auth.uid() IN (SELECT user_id FROM premium_users)
  OR (
    keyhippo.key_uid() IS NOT NULL
    AND keyhippo.key_uid() IN (SELECT user_id FROM premium_users)
    AND EXISTS (
      SELECT 1
      FROM keyhippo.get_api_key_metadata(keyhippo.key_uid()) AS key_meta
      WHERE key_meta.permission = 'premium'
    )
  )
);

This policy grants access to premium content for users with premium status, whether they’re authenticated via session or an API key with premium permissions.

​

Performance Considerations

KeyHippo is designed to maintain the performance characteristics of Supabase RLS:

1. Efficient Evaluation: KeyHippo functions are optimized for quick evaluation within RLS policies.
2. No Additional Queries: API key validation doesn’t introduce additional database queries during policy evaluation.
3. Caching Compatibility: Works with Supabase’s caching mechanisms for RLS policies.

​

Best Practices for Integration

1. Gradual Adoption: Start by adding KeyHippo to a few non-critical policies before widespread implementation.
2. Consistent Logic: Ensure that the logic for API key access mirrors that of session-based access where appropriate.
3. Testing: Thoroughly test policies with both authentication methods to ensure consistent behavior.
4. Documentation: Clearly document which policies have been enhanced with KeyHippo functionality.

​

Handling Edge Cases

1. Mixed Authentication: Consider how to handle scenarios where both session tokens and API keys are present in a request.
2. Fallback Behavior: Decide on and implement consistent fallback behavior when API key authentication fails.

​

Upgrading and Maintenance

1. Version Compatibility: Keep KeyHippo updated to ensure ongoing compatibility with Supabase updates.
2. Policy Reviews: Regularly review and test RLS policies, especially after Supabase or KeyHippo updates.
3. Performance Monitoring: Monitor query performance to ensure KeyHippo integration doesn’t introduce unexpected slowdowns.