API Key Management Instructions

Important: The SAM.gov API key expires every 88 days. You must update it in your Convex environment to keep the scraper working.

Current Status

Current API Key Set Date

Next Expiry Date

Days Remaining

⚠️ API Key expires soon!

API Key Validity 0 of 88 days remaining

0 days 88 days

1 Get a New SAM.gov API Key

Visit the SAM.gov API registration page to get a new API key:

https://sam.gov/workspace/profile/account-details

Register for API Access

Create an account or log in to your existing SAM.gov account

Request API Key

Navigate to the "Get Opportunities Public API" section and request a new API key

Copy the Key

Save the API key securely - you'll need it for the next step

2 Update Environment Variable in Convex

You need to update the SAMdotGOV_KEY environment variable in your Convex deployment:

Note: This requires access to your Convex dashboard or CLI access to your project.

Option A: Using Convex Dashboard

1. Go to Convex Dashboard

Visit dashboard.convex.dev and select your project

2. Navigate to Settings

Go to the "Settings" tab in your project dashboard

3. Update Environment Variables

Find the SAMdotGOV_KEY variable and update it with your new API key

4. Deploy Changes

Save the changes and wait for the deployment to complete

Option B: Using Convex CLI

npx convex env set SAMdotGOV_KEY "your-new-api-key-here"

Replace "your-new-api-key-here" with your actual API key from SAM.gov

3 Test the New API Key

After updating the API key, test that it's working correctly:

1. Go to Dashboard

Return to the main dashboard

2. Run a Test Scrape

Click the "Run Scraper" button to test the new API key

3. Check for Errors

If you see mock data or errors, the API key may not be working correctly

Success! If you see real opportunities from SAM.gov (not mock data), your API key is working correctly.

Troubleshooting

API key not working - getting mock data

This usually means the API key is invalid or expired. Double-check that you copied the key correctly and that it's active in your SAM.gov account.

Getting "An invalid api_key was supplied" errors

This indicates the API key is invalid or has expired. Request a new key from SAM.gov and update it in your Convex environment.

Getting "No api_key was supplied" errors

This means the SAMdotGOV_KEY environment variable is not set in your Convex deployment. Make sure you've added the API key to your environment variables.

Getting "Bad Request" errors

This usually means there's an issue with the request parameters. Check that your date formats are correct (MM/dd/yyyy) and that all required parameters are provided.

Getting "No Data found" responses

This is normal and indicates the API is working correctly, but no opportunities match your search criteria. Try expanding your date range or adjusting your search parameters.

Environment variable not updating

Make sure you're updating the correct environment variable name: SAMdotGOV_KEY. After updating, wait a few minutes for the deployment to complete.

Set a Reminder

Don't forget to set a calendar reminder for 85 days from now to update your API key before it expires!

Reminder: Update SAM.gov API key in 85 days (expires in 88 days)