Skip to main content

Authentication

Learn how to authenticate with the Games API using Nile’s multi-tenant authentication.

Tenant-Based Authentication

The Games API uses tenant-based authentication via Nile SDK for complete data isolation.

Required Header

All API requests must include a tenant ID header:
x-tenant-id: <your-tenant-uuid>

Authentication Methods

For browser-based applications:
// Nile SDK handles authentication automatically
const tenantNile = nile.getInstance({
  tenantId: 'tenant-uuid',
  userId: 'user-uuid',
  api: {
    token: cookies.get('nile.session-token')?.value,
  },
});
Flow:
  1. User signs in via Nile auth
  2. Session token stored in cookie
  3. API requests automatically include token
  4. Tenant context set from session

2. API Key-Based (Programmatic)

For server-to-server or programmatic access:
curl -X GET "https://api.domain/games/wheel/profiles" \
  -H "x-tenant-id: 00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer your-api-key"

Multi-Tenancy

Tenant Isolation

Each tenant’s data is completely isolated:
-- All tables have tenant_id foreign key
CREATE TABLE profiles (
  id_profile UUID PRIMARY KEY,
  tenant_id UUID NOT NULL REFERENCES tenants(id),
  ...
);
When you query within a tenant context:
const db = await getTenantDb('tenant-uuid');
const profiles = await db.query('SELECT * FROM profiles');
// Automatically scoped to tenant - no WHERE clause needed!

Creating Tenants

# Via psql
psql <connection-string>
INSERT INTO tenants (id, name) VALUES ('your-uuid', 'Your Company');

# Via Nile SDK
const tenant = await nile.api.tenants.createTenant({
  name: 'Your Company',
});

Listing Tenants

const tenants = await nile.db.query(
  'SELECT id, name FROM tenants ORDER BY name'
);

Connection Details

Database URL Format

postgres://<user>:<password>@<host>/<database>
Example:
postgres://0199f19f-2258-7fbd-8cbe-cfb258318f2d:[email protected]/sendsational

Environment Variables

DATABASE_NILEDB_USER="0199f19f-2258-7fbd-8cbe-cfb258318f2d"
DATABASE_NILEDB_PASSWORD="c419a214-33ba-4086-9830-c34f91feea0d"
DATABASE_NILEDB_API_URL="https://us-west-2.api.thenile.dev/v2/databases/<db-id>"
DATABASE_NILEDB_POSTGRES_URL="postgres://us-west-2.db.thenile.dev/sendsational"

Security Best Practices

1. Never Hardcode Credentials

Bad:
const nile = await NileServer({
  user: '0199f19f-2258-7fbd-8cbe-cfb258318f2d',
});
Good:
const nile = await NileServer({
  // Reads from DATABASE_NILEDB_* env variables
});

2. Use Secure Cookies in Production

const nile = await NileServer({
  secureCookies: process.env.VERCEL === '1', // HTTPS only in prod
});

3. Validate Tenant Access

// Verify user has access to tenant
const hasAccess = await nile.api.tenants.getUserTenants(userId);
if (!hasAccess.find(t => t.id === tenantId)) {
  throw new Error('Unauthorized');
}

Example: Full Authentication Flow

import NileServer from '@niledatabase/server';

// 1. Initialize Nile
const nile = await NileServer({
  debug: true,
  secureCookies: process.env.VERCEL === '1',
});

// 2. Get user from session
const user = await nile.api.users.me();

// 3. Get user's tenants
const tenants = await nile.api.users.getUserTenants(user.id);

// 4. Select tenant (or from cookie)
const selectedTenant = tenants[0].id;

// 5. Create tenant-scoped instance
const tenantNile = nile.getInstance({
  tenantId: selectedTenant,
  userId: user.id,
  api: {
    token: cookies.get('nile.session-token')?.value,
  },
});

// 6. Query tenant data
const profiles = await tenantNile.db.query('SELECT * FROM profiles');

Testing

Development Tenant

For testing, use a default tenant ID:
DEFAULT_TENANT_ID="00000000-0000-0000-0000-000000000000"

Create Test Tenant

INSERT INTO tenants (id, name) VALUES 
  ('00000000-0000-0000-0000-000000000000', 'Test Tenant');

Troubleshooting

”Tenant not found”

Ensure tenant exists:
SELECT * FROM tenants WHERE id = 'your-tenant-uuid';

“Authentication failed”

Check environment variables:
echo $DATABASE_NILEDB_USER
echo $DATABASE_NILEDB_PASSWORD

“Connection refused”

Verify connection string:
psql <your-connection-string>

Learn More