Kroger OAuth Setup Guide

This guide walks you through setting up Kroger OAuth authentication for the Personal Shopper application.

1. Kroger Developer Account: You need to register as a developer with Kroger
2. Val Town Account: Your application should be deployed on Val Town

1. Visit the Kroger Developer Portal
2. Create an account or sign in
3. Create a new application
4. Note down your Client ID and Client Secret

In your Kroger application settings, set the redirect URI to:

https://your-val-name.web.val.run/auth/callback

Replace your-val-name with your actual Val Town username and val name.

In your Val Town environment, set these variables:

• KROGER_CLIENT_ID: Your Kroger application's client ID
• KROGER_CLIENT_SECRET: Your Kroger application's client secret
• KROGER_REDIRECT_URI: The redirect URI you registered (e.g., https://your-val-name.web.val.run/auth/callback)

1. Go to your Val Town dashboard
2. Click on your val
3. Go to the "Environment" tab
4. Add the three variables listed above

1. Visit your application URL
2. Click "Connect with Kroger"
3. You should be redirected to Kroger's login page
4. After logging in and authorizing, you'll be redirected back to your app

When a user clicks "Connect with Kroger", they're redirected to:

https://api.kroger.com/v1/connect/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=profile.compact cart.basic:write product.compact&
  state=RANDOM_STATE_STRING

Kroger redirects back to your callback URL with:

• code: Authorization code to exchange for tokens
• state: The same state value you sent (for security)

Your app exchanges the authorization code for:

• access_token: Used to make API calls on behalf of the user
• refresh_token: Used to get new access tokens when they expire
• expires_in: How long the access token is valid (in seconds)

Your app uses the access token to get the user's Kroger profile ID from:

GET https://api.kroger.com/v1/identity/profile
Authorization: Bearer ACCESS_TOKEN

The app creates a local user record and sets a session cookie for future requests.

The application requests these OAuth scopes:

• profile.compact: Access to user's basic profile information
• cart.basic:write: Ability to add items to the user's cart
• product.compact: Access to search products in the catalog

• State Parameter: Prevents CSRF attacks during OAuth flow
• HTTP-Only Cookies: Session cookies are not accessible via JavaScript
• Token Refresh: Automatic refresh of expired access tokens
• Secure Storage: Tokens are stored securely in the database

• Ensure all three environment variables are set correctly
• Check that there are no extra spaces in the variable values

• Verify the redirect URI in Kroger's developer portal matches exactly
• Ensure you're using HTTPS (required by Kroger)

• Double-check your client ID and secret
• Ensure your Kroger application is active

• The app automatically handles token refresh
• If refresh fails, users will need to re-authenticate

Once OAuth is configured, these endpoints become available:

• GET /auth/login - Start OAuth flow
• GET /auth/callback - Handle OAuth callback
• POST /auth/logout - End user session

• GET /api/user - Get current user info
• PUT /api/user/location - Update preferred store location

• GET /api/guidance - Get user's shopping preferences
• POST /api/guidance - Add new preference
• GET /api/selections - Get user's saved product selections
• POST /api/selections - Save new product selection

After OAuth is working:

1. Test the full flow with a real Kroger account
2. Implement product search using the Kroger Products API
3. Add cart management using the Kroger Cart API
4. Integrate AI/LLM for intelligent product selection
5. Build the shopping list interface

For Kroger API issues:

• Kroger Developer Documentation
• Kroger Developer Support

For Val Town issues:

• Val Town Documentation
• Val Town Discord