Resolving 403 Forbidden errors when calling Moov API endpoints

Last updated 8 months ago

If you're receiving 403 Forbidden errors when making requests to Moov API endpoints, this typically indicates an authentication or authorization issue. Here are the most common causes and solutions:

Check your API endpoint URL

Ensure you're using the correct API endpoint URL without version numbers:

• Correct: https://api.moov.io/oauth2/token
• Incorrect: https://api.moov.io/v1/oauth2/token

Remove version prefixes from your API URLs if present, as this can cause 403 errors.

Verify authentication method

Make sure you're using the correct authentication credentials:

• For Basic Auth: Use your public key as username and private key as password
• For OAuth tokens: Ensure the token has the correct scopes for the endpoint you're calling

Add required headers for client-side requests

When making requests from a client application or when using OAuth tokens, you must include Origin and Referer headers:

Origin: https://yourdomain.com
Referer: https://yourdomain.com

The domain in these headers must be whitelisted in your API key settings in the Moov dashboard.

Whitelist your domain

Ensure your domain is added to the allowed domains list for your API key:

1. Go to your Moov dashboard
2. Navigate to Developers > API Keys
3. Edit your API key and add your domain to the allowed domains list
4. For local development, add http://localhost:3000 or your local development URL

Use the correct account ID

When making requests that require an account ID in the URL path:

• Use your own account ID (the facilitator account) for creating transfers
• Ensure the account ID exists and is connected to your organization
• For connected accounts, verify you have the proper permissions

Check OAuth token scopes

If using OAuth tokens, ensure your token includes the required scopes for the endpoint. For example:

• Creating accounts: /accounts.write
• Creating transfers: /accounts/{accountID}/transfers.write
• Reading institutions: /institutions.read

Geographic restrictions

Moov API requests from certain geographic locations may be blocked. If you're making requests from outside the US and receiving 403 errors with Cloudflare content, contact support to whitelist your specific IP address.

Terms of Service token issues

For Terms of Service acceptance, ensure:

• The TOS token is generated on the server with proper authentication
• The client and server IP addresses are different when accepting terms
• You're using OAuth tokens (not Basic Auth) for TOS token generation

Still getting 403 errors?

If you continue to receive 403 errors after checking the above:

1. Note the x-request-id from the response headers
2. Contact Moov support with the request ID for detailed investigation
3. Include your account ID and the specific endpoint you're trying to access