# API Key Restrictions Troubleshooting Guide

**Last Updated:** 2026-01-19

## Overview

Even if Cloud Vision API appears enabled in Google Cloud Console, you may still receive 403 SERVICE_DISABLED errors if your API key restrictions don't allow Vision API. This guide helps you diagnose and fix API key restriction issues.

## Common Scenario

**Symptom:**
- Vision API shows as "Enabled" in Google Cloud Console
- API key is valid and works for other APIs (like Google Maps)
- But Vision API calls return 403 SERVICE_DISABLED

**Root Cause:**
- API key has "API restrictions" enabled
- Vision API is not included in the allowed APIs list

## Step-by-Step Fix

### Step 1: Identify Your API Key

1. **Find which API key you're using:**
   ```bash
   php v2/scripts/ocr-diagnose-api-key.php
   ```
   
   This shows:
   - Key preview
   - Key source (environment variable, constant, or fallback)
   - Project number

### Step 2: Check API Key Restrictions

1. **Navigate to API Credentials:**
   - Go to: https://console.cloud.google.com/apis/credentials
   - Or use project-specific URL: https://console.cloud.google.com/apis/credentials?project=YOUR_PROJECT_NUMBER

2. **Find Your API Key:**
   - Look for the key that matches your key preview
   - If using fallback, look for the Google Maps API key

3. **Click to Edit:**
   - Click on the API key name to open edit dialog

4. **Check "API restrictions" Section:**
   
   **Scenario A: "Don't restrict key"**
   - ✅ This should work (unless other issues)
   - No changes needed
   - Skip to Step 3
   
   **Scenario B: "Restrict key"**
   - ⚠️ This is likely the issue
   - Check the list of allowed APIs
   - Look for "Cloud Vision API" in the list
   
   **If Vision API is NOT in the list:**
   - Click "Restrict key"
   - Click "Select APIs"
   - Search for "Cloud Vision API"
   - Check the box next to "Cloud Vision API"
   - Click "Save"
   - Wait 1-2 minutes for changes to propagate

### Step 3: Verify Other Restrictions

While editing your API key, also check:

1. **Application restrictions:**
   - If "HTTP referrers" is set, ensure your domain is allowed
   - If "IP addresses" is set, ensure your server IP is allowed
   - These shouldn't block Vision API, but worth checking

2. **API restrictions:**
   - Ensure "Cloud Vision API" is checked
   - You can have multiple APIs allowed (e.g., Maps API + Vision API)

### Step 4: Test After Changes

After updating restrictions:

1. **Wait 1-2 minutes** for changes to propagate
2. **Test the API:**
   ```bash
   php v2/scripts/quick-vision-api-test.php
   ```
3. **Check diagnostics:**
   - Visit: `/v2/admin/ocr-diagnostics.php?debug=1`

## Visual Guide

### Correct Configuration

**API Restrictions:**
```
☑ Restrict key
  Select APIs:
    ☑ Cloud Maps API
    ☑ Cloud Vision API    ← Must be checked
    ☑ Other APIs...
```

**Or:**
```
☑ Don't restrict key    ← Also works
```

### Incorrect Configuration

**API Restrictions:**
```
☑ Restrict key
  Select APIs:
    ☑ Cloud Maps API
    ☐ Cloud Vision API    ← Missing! This causes 403 error
    ☑ Other APIs...
```

## Quick Reference URLs

Replace `YOUR_PROJECT_NUMBER` with your actual project number (e.g., `842128635996`):

- **API Credentials:** https://console.cloud.google.com/apis/credentials?project=YOUR_PROJECT_NUMBER
- **Enable Vision API:** https://console.cloud.google.com/apis/api/vision.googleapis.com/overview?project=YOUR_PROJECT_NUMBER
- **Billing:** https://console.cloud.google.com/billing?project=YOUR_PROJECT_NUMBER

## Troubleshooting Checklist

- [ ] API key has "Cloud Vision API" in allowed APIs (if restrictions enabled)
- [ ] Vision API is enabled in the project
- [ ] Billing is active and linked to project
- [ ] Waited 5-10 minutes after making changes
- [ ] Tested with: `php v2/scripts/quick-vision-api-test.php`
- [ ] Checked diagnostics dashboard: `/v2/admin/ocr-diagnostics.php?debug=1`

## Related Documentation

- [Vision API Setup Guide](GOOGLE_VISION_API_SETUP.md)
- [Enablement Verification](API_ENABLEMENT_VERIFICATION.md)
- [Implementation Summary](IMPLEMENTATION_SUMMARY.md)