BYOK Setup Guide

This guide walks through uploading and validating your Google Gemini API key.

Prerequisites

A Google Cloud project with the Generative Language API enabled
A Gemini API key from Google AI Studio
tenant_admin role on your GoTamil tenant

Step 1: Upload Your Credential


curl -X POST "$GOTAMIL_API/v1/admin/byok/providers/gemini/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "credential": "AIza...",
    "mode": "create",
    "label": "Production Gemini key"
  }'

This stores your key in Google Cloud Secret Manager and transitions your onboarding state to validation_pending.

Step 2: Validate the Credential


curl -X POST "$GOTAMIL_API/v1/admin/byok/providers/gemini/credentials/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)"

The API makes a test call to Gemini to verify the key works. A successful validation returns:


{
  "tenant_id": "your-tenant",
  "provider": "gemini",
  "validation_status": "passed",
  "onboarding_state": "certification_pending",
  "checked_at": "2026-01-15T10:30:00Z",
  "error": null
}

Step 3: Check Onboarding Status


curl "$GOTAMIL_API/v1/admin/onboarding/status" \
  -H "Authorization: Bearer $TOKEN"

Your BYOK summary should show configured: true and validation_status: "passed".

Rotating Keys

To replace an existing key, use mode: "rotate":


curl -X POST "$GOTAMIL_API/v1/admin/byok/providers/gemini/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "credential": "AIza-new-key...",
    "mode": "rotate",
    "label": "Rotated Jan 2026"
  }'

After rotating, you must re-validate the credential.

Troubleshooting

Validation Error	Cause	Fix
401 auth error	Invalid API key	Double-check the key in Google AI Studio
429 quota error	Key has exceeded quota	Check your Google Cloud quota limits
Network error	Connectivity issue	Ensure your environment can reach `generativelanguage.googleapis.com`