# Microsoft Graph API Setup for Workspace Creation

## Issue

When creating a workspace, you may encounter this error:

```
"Error converting value \"email@example.com\" to type 'System.Guid'"
```

This occurs because Microsoft Fabric API requires the user's **Azure AD Object ID (GUID)**, not their email address.

## Solution

### Prerequisites

Your Azure App Registration must have the correct Microsoft Graph API permissions.

### Step 1: Add Microsoft Graph API Permissions

1. Go to [Azure Portal](https://portal.azure.com)
2. Navigate to **Azure Active Directory** → **App registrations**
3. Find and click on your Fabric application
4. Click **API permissions** in the left menu
5. Click **Add a permission**
6. Select **Microsoft Graph**
7. Choose **Application permissions** (NOT Delegated permissions)
8. Search for and select: **User.Read.All**
9. Click **Add permissions**

### Step 2: Grant Admin Consent

⚠️ **Important**: Application permissions require admin consent.

1. In the API permissions page, click **Grant admin consent for [Your Organization]**
2. Click **Yes** to confirm
3. Verify the status shows a green checkmark with "Granted for [Your Organization]"

### Step 3: Verify Permissions

Your Azure App should now have at least these permissions:

| API              | Permission Name                           | Type        | Admin Consent |
| ---------------- | ----------------------------------------- | ----------- | ------------- |
| Microsoft Fabric | https://api.fabric.microsoft.com/.default | Application | Required      |
| Microsoft Graph  | User.Read.All                             | Application | Required      |

### Step 4: Test the Setup

Run the following artisan command to test your configuration:

```bash
php artisan fabric:test-graph your-email@domain.com
```

This will:

- ✅ Test Graph API token generation
- ✅ Fetch your user's Object ID
- ✅ Display your Azure AD profile information

### Step 5: Try Creating a Workspace

After confirming the test passes, try creating a workspace through the web UI.

## Troubleshooting

### Error: "Authorization_RequestDenied"

**Cause**: Missing or insufficient permissions  
**Fix**: Ensure "User.Read.All" permission is added AND admin consent is granted

### Error: "Request_ResourceNotFound"

**Cause**: User email not found in Azure AD  
**Fix**:

- Verify the email address is correct
- Ensure the user exists in your Azure AD tenant
- Check you're using the correct Tenant ID

### Error: "InvalidAuthenticationToken"

**Cause**: Token generation failed  
**Fix**:

- Verify Client ID, Tenant ID, and Client Secret are correct
- Ensure the Client Secret hasn't expired
- Check if the Azure App still exists

### Error: "Forbidden"

**Cause**: Admin consent not granted  
**Fix**: Follow Step 2 above to grant admin consent

## How It Works

When you create a workspace:

1. System checks if your Object ID is stored in the database
2. If not, it calls Microsoft Graph API: `GET /v1.0/users/{email}`
3. Graph API returns your user profile including the Object ID (GUID)
4. Object ID is saved to your user record for future use
5. Workspace is created and you're assigned as Admin using the Object ID

## Additional Resources

- [Microsoft Graph API Documentation](https://learn.microsoft.com/en-us/graph/api/user-get)
- [Azure AD App Permissions](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent)
- [Microsoft Fabric API](https://learn.microsoft.com/en-us/rest/api/fabric/)

## Need Help?

If you continue to experience issues:

1. Check logs: `storage/logs/laravel.log`
2. Run the test command: `php artisan fabric:test-graph`
3. Verify all API permissions are granted with admin consent
4. Ensure your email exists in Azure AD