Reference

​

Installation

Install the KeyHippo extension in your Supabase database:

SELECT dbdev.install('keyhippo@keyhippo');
CREATE EXTENSION "keyhippo@keyhippo" VERSION '0.0.33';

​

Schemas

KeyHippo creates and uses the following schemas:

• keyhippo: Main schema for KeyHippo functions and tables
• keyhippo_internal: Internal schema for KeyHippo helper functions

​

Functions

FUNCTION keyhippo.create_api_key(id_of_user TEXT, key_description TEXT) RETURNS TEXT

FUNCTION keyhippo.revoke_api_key(id_of_user TEXT, secret_id TEXT) RETURNS VOID

FUNCTION keyhippo.get_api_key_metadata(id_of_user UUID) RETURNS TABLE (
  api_key_id UUID,
  name TEXT,
  permission TEXT,
  last_used TIMESTAMPTZ,
  created TIMESTAMPTZ,
  total_uses BIGINT,
  success_rate DOUBLE PRECISION,
  total_cost DOUBLE PRECISION,
  revoked TIMESTAMPTZ
)

FUNCTION auth.keyhippo_check(owner_id UUID) RETURNS BOOLEAN

FUNCTION keyhippo.key_uid() RETURNS UUID

​

Tables

KeyHippo creates and manages several tables to store API key information:

• keyhippo.user_ids: Stores user IDs
• keyhippo.api_key_id_owner_id: Maps API key IDs to owner IDs
• keyhippo.api_key_id_name: Stores API key names/descriptions
• keyhippo.api_key_id_permission: Stores permissions for each API key
• keyhippo.api_key_id_created: Stores creation timestamps for API keys
• keyhippo.api_key_id_last_used: Tracks the last usage of each API key
• keyhippo.api_key_id_total_use: Counts total uses of each API key
• keyhippo.api_key_id_success_rate: Tracks success rates of API key usage
• keyhippo.api_key_id_total_cost: Tracks total cost associated with each API key
• keyhippo.api_key_id_revoked: Stores revocation information for API keys

​

RLS Policies

KeyHippo automatically sets up Row Level Security (RLS) policies on its tables. Here’s an example of how to create a custom RLS policy that incorporates KeyHippo authentication:

CREATE POLICY "users_read_own_data"
ON public.user_data
FOR SELECT
USING (
  auth.uid() = user_id
  OR auth.keyhippo_check(user_id)
);

This policy allows users to read their own data when authenticated either through a session token (auth.uid()) or a valid API key (auth.keyhippo_check()).

​

Vault Integration

KeyHippo uses Supabase Vault for storing sensitive information. The following secrets are automatically set up:

• project_api_key_secret: Used for API key hashing
• project_jwt_secret: Used for JWT signing in API key generation

​

Troubleshooting

Here are solutions to common issues when working with the KeyHippo extension:

For more detailed troubleshooting, refer to the KeyHippo GitHub repository or consult the full documentation.