# Adobe API Credentials Setup

This guide explains how to set up and use Adobe API credentials with the scripts in this repository, updated with the latest information from Adobe (April 22, 2025).

## Token Generation Workflow

The scripts support dynamic token generation using client credentials, removing the need for manually pasting static access tokens. According to Adobe's latest guidelines, the workflow is as follows:

1. You provide a client ID and client secret (from Adobe)
2. The scripts automatically generate OAuth tokens with correct scopes
3. Tokens are cached locally to minimize API calls
4. Expired tokens are automatically refreshed (tokens expire after 24 hours)

## Using Client Credentials

### Option 1: Command Line Parameters

You can provide the client secret directly when running commands:

```bash
# Generate a new token
python adobe_ps_api.py generate-token --client-secret YOUR_CLIENT_SECRET

# Run any command with token generation
python adobe_ps_api.py test-api --client-secret YOUR_CLIENT_SECRET
python adobe_ps_api.py update-text path/to/file.json --client-secret YOUR_CLIENT_SECRET
```

### Option 2: Edit Configuration File

You can edit the `config.py` file to include your client credentials:

```python
# Adobe API Credentials
ADOBE_CLIENT_ID = "your_client_id"
ADOBE_CLIENT_SECRET = "your_client_secret"
```

**Important**: Never commit the `config.py` file with real credentials to version control. Consider using environment variables in production.

### Option 3: Environment Variables

For production use, set environment variables:

```bash
# Set environment variables
export ADOBE_CLIENT_ID="your_client_id"
export ADOBE_CLIENT_SECRET="your_client_secret"

# Update the config.py to use environment variables:
ADOBE_CLIENT_ID = os.environ.get("ADOBE_CLIENT_ID", "default_client_id")
ADOBE_CLIENT_SECRET = os.environ.get("ADOBE_CLIENT_SECRET", "")
```

## Token Cache

Generated tokens are cached in a file named `.adobe_token_cache.json` in the script directory. This cache:

- Reduces the number of authentication calls
- Persists between script runs
- Automatically refreshes expired tokens
- Can be manually cleared with `rm .adobe_token_cache.json`

## API Scopes

According to Adobe's latest documentation, the correct scopes are specific to each service:

### For Photoshop REST API
The default scope is `openid,AdobeID,read_organizations`:

```bash
python adobe_ps_api.py generate-token --client-secret YOUR_SECRET --scopes "openid,AdobeID,read_organizations"
```

### For Firefly REST API
The required scope is `openid,AdobeID,firefly_api,ff_apis`:

```bash
python adobe_ps_api.py generate-token --client-secret YOUR_SECRET --scopes "openid,AdobeID,firefly_api,ff_apis"
```

These specific scopes have been confirmed by Adobe as the correct ones to use. Using incorrect scopes may result in authentication failures or limited access to API functionality.

## Troubleshooting

If you encounter API errors after token generation:

1. **Token Expiration**: Tokens expire after 24 hours - if you get authentication errors, try generating a new token
2. **Incorrect Endpoints**: Make sure you're using the correct endpoints:
   - For Photoshop REST API: `https://image.adobe.io/pie/psdService/actionJSON`
   - Other subdomains (`photoshop.adobe.io` and `photoshop-services.adobe.io`) are not used
3. **Storage Issues**: Adobe does not provide pre-signed URL generation - ensure you're using external storage like GCS
4. **Scope Problems**: Use the correct scope for the specific API you're accessing
5. **Network Issues**: Check your network configuration if DNS resolution fails for Adobe domains

For detailed status information and current implementation status, consult the API-STATUS.md file.

## API Endpoint Information

Based on Adobe's latest confirmation:

1. **Authentication**: `https://ims-na1.adobelogin.com/ims/token/v3` (POST with form data)
2. **Photoshop REST API endpoints**:
   - Action JSON: `https://image.adobe.io/pie/psdService/actionJSON`
   - Product Crop: `https://image.adobe.io/pie/psdService/productCrop`
3. **Firefly API**:
   - Upload: `https://developer.adobe.com/firefly-services/docs/firefly-api/guides/api/upload_image/V2/`

## Storage Solution

Adobe APIs do not provide storage for files. You must use an external storage provider like Google Cloud Storage, Amazon S3, or Azure Storage to host your files and generate pre-signed URLs for access by the Adobe APIs.