# GCP IAM Roles Required for Vision API Setup

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

## Quick Start

**Can't find "Add User" button?** See [How to Add Users Guide](GCP_ADD_USER_GUIDE.md) - the button is labeled **"+ Zugriffsrechte erteilen"** (German) or **"Grant Access"** (English).

## Overview

To enable Vision API and manage API key restrictions on your own, you need specific Google Cloud Platform IAM roles. This document lists the exact roles to request from your team lead.

## Required Roles

### 1. Service Usage Admin (Primary Role)

**Role ID:** `roles/serviceusage.serviceUsageAdmin`

**What it allows:**
- ✅ Enable/disable APIs (including Vision API)
- ✅ View which APIs are enabled
- ✅ Manage service quotas
- ✅ View billing information for enabled services
- ✅ Inspect service operations

**Permissions included:**
- `serviceusage.services.enable` - Enable APIs
- `serviceusage.services.disable` - Disable APIs
- `serviceusage.services.get` - View API status
- `serviceusage.services.list` - List enabled APIs
- `serviceusage.quotas.get` - View quotas
- `serviceusage.operations.get` - View operations

**Use case:** This role is **required** to enable Vision API in the Google Cloud Console.

### 2. API Keys Admin (For API Key Management)

**Role ID:** `roles/serviceusage.apiKeysAdmin`

**What it allows:**
- ✅ Create new API keys
- ✅ Edit existing API keys (including restrictions)
- ✅ Delete API keys
- ✅ View API key values
- ✅ Update API key restrictions (add/remove allowed APIs)
- ✅ Regenerate API keys

**Permissions included:**
- `apikeys.keys.create` - Create API keys
- `apikeys.keys.update` - Edit API keys (including restrictions)
- `apikeys.keys.delete` - Delete API keys
- `apikeys.keys.get` - View API key details
- `apikeys.keys.getKeyString` - View API key value
- `apikeys.keys.list` - List all API keys

**Use case:** This role is **required** to edit API key restrictions and add "Cloud Vision API" to allowed APIs.

### 3. Billing Account User (Optional - for billing verification)

**Role ID:** `roles/billing.user`

**What it allows:**
- ✅ View billing account information
- ✅ View billing account status
- ✅ Link projects to billing accounts (if you have project-level permissions)

**Note:** You typically only need this if you need to verify billing status. Your team lead may prefer to handle billing linking themselves.

## Minimum Required Roles

To complete Vision API setup independently, you need **at minimum**:

1. ✅ **Service Usage Admin** - To enable Vision API
2. ✅ **API Keys Admin** - To edit API key restrictions

## Request Template for Team Lead

Here's a template you can use to request these roles:

---

**Subject:** Request GCP IAM Roles for Vision API Setup

Hi [Team Lead],

I need to enable Google Cloud Vision API for the business card OCR feature. To do this independently, I need the following IAM roles on project `842128635996` (or the project our Google Maps API key belongs to):

**Required Roles:**
1. **Service Usage Admin** (`roles/serviceusage.serviceUsageAdmin`)
   - Needed to enable Vision API in the project
   
2. **API Keys Admin** (`roles/serviceusage.apiKeysAdmin`)
   - Needed to edit API key restrictions to add Vision API to allowed APIs

**My GCP Account Email:** [your-email@ordio.com]

**Project:** ordio-256916 (Project Number: 842128635996)

**Purpose:** Enable Vision API and configure API key restrictions for business card OCR functionality.

Thanks!

---

## Role Assignment Steps (For Team Lead)

If your team lead needs to assign these roles:

1. **Navigate to IAM & Admin:**
   - Go to: https://console.cloud.google.com/iam-admin/iam?project=ordio-256916
   - Or: IAM & Admin → IAM in Google Cloud Console

2. **Find the "Add User" Button:**
   - Look for **"+ Zugriffsrechte erteilen"** (German) or **"Grant Access"** (English)
   - This is the button to add users - it's NOT labeled "Add User"
   - It's located at the top of the permissions table
   - See [Add User Guide](GCP_ADD_USER_GUIDE.md) for detailed visual instructions

3. **Add Role:**
   - Click **"+ Zugriffsrechte erteilen"** or **"Grant Access"**
   - In **"Neue Hauptkonten"** (New principals) field, enter the user's email
   - Click **"Rolle auswählen"** (Select role) dropdown
   - Add role: `Service Usage Admin` (`roles/serviceusage.serviceUsageAdmin`)
   - Click **"Weitere Rolle hinzufügen"** (Add another role)
   - Add role: `API Keys Admin` (`roles/serviceusage.apiKeysAdmin`)
   - Click **"Speichern"** (Save)

4. **Verify:**
   - User should appear in the permissions list
   - Roles take effect immediately (no email notification needed)

## What You Can Do With These Roles

Once you have these roles, you can:

✅ **Enable Vision API:**
   - Navigate to API Library
   - Search for "Cloud Vision API"
   - Click "Enable"

✅ **Edit API Key Restrictions:**
   - Go to APIs & Services → Credentials
   - Find your API key
   - Click to edit
   - Add "Cloud Vision API" to allowed APIs
   - Save changes

✅ **View API Status:**
   - Check which APIs are enabled
   - View API quotas and usage
   - Monitor API operations

## What You Cannot Do (Requires Additional Roles)

❌ **Link Billing Accounts** - Requires `roles/billing.admin` or `roles/billing.user` + project owner
❌ **Create New Projects** - Requires `roles/resourcemanager.projectCreator` or project owner
❌ **Modify IAM Permissions** - Requires `roles/iam.securityAdmin` or project owner
❌ **Delete Projects** - Requires project owner

## Security Best Practices

- **Least Privilege:** Only request the minimum roles needed
- **Project-Level:** These roles should be assigned at the project level, not organization level
- **Temporary Access:** Consider requesting temporary access if this is a one-time task
- **Audit:** Your team lead may want to review role assignments periodically

## Alternative: Read-Only Roles (If You Just Need to Verify)

If you only need to **check** status but not make changes, you can request:

- **Service Usage Consumer** (`roles/serviceusage.serviceUsageConsumer`) - Can view enabled APIs but not enable them
- **API Keys Viewer** (`roles/serviceusage.apiKeysViewer`) - Can view API keys but not edit them

However, to actually **enable** Vision API and **edit** restrictions, you need the Admin roles listed above.

## References

- [Google Cloud IAM Roles Documentation](https://cloud.google.com/iam/docs/roles)
- [Service Usage Roles](https://cloud.google.com/iam/docs/roles-permissions/serviceusage)
- [API Keys Roles](https://cloud.google.com/iam/docs/roles-permissions/apikeys)