Skip to content

Tenants and API keys

Every client request needs an API key, and every API key resolves to one tenant. Create at least one tenant and key before clients can use the platform.

Both live in the gateway database. POSTGRES_USER and POSTGRES_DB are the values from your environment file.

Create a tenant

Open a SQL shell on the gateway database. With Docker Compose, run this in the rag-docker directory:

docker compose exec gateway-database psql -U POSTGRES_USER POSTGRES_DB

With quadlets, the container is named gateway-database:

podman exec -it gateway-database psql -U POSTGRES_USER POSTGRES_DB

Create the tenant. The name is for your own reference:

INSERT INTO identity_tenants (id, name) VALUES (gen_random_uuid(), 'INSERT_TENANT_NAME');
SELECT id, name FROM identity_tenants;

Note the tenant's id (a UUID).

Create an API key

Run utilities/create-api-key.sh from the rag-docker repository. It needs bash, openssl and python3, and it can run on any machine, not only the deployment host:

utilities/create-api-key.sh --tenant TENANT_UUID --description "INSERT_TENANT_DESCRIPTION"

The description is just some string for readability, it doesn't really matter.

The script prints:

Output Meaning
CLIENT-KEY The API key. Hand it to the client developer. It's stored only as a hash, so it can't be shown again
LOOKUP-KEY The first 12 characters of the key, used to find it in the database
SALT, DATABASE-KEY The salt and the salted hash that the database stores
PostgreSQL-INSERT The ready-made INSERT statement for identity_tenant_authentications

Run the printed INSERT statement in the SQL shell. This activates the key.

Revoke a key

Delete its row from identity_tenant_authentications, for example by its lookup value. RAG Web caches resolved keys in Valkey for ApiKeyAuthentication__AbsoluteExpirationSeconds (default 300 seconds), so a revoked key can keep working for up to that long.