OAuth2 Client Credentials Flow

This guide walks you through setting up OAuth2 authentication to access the Fospha API.

Before you begin, ensure you have:

• Valid Fospha API credentials (app_client_id and app_client_secret )
• Access to make HTTPS requests from your application

If you do not have credentials yet, please contact Fospha support to register your brand and application.

Use the OAuth2 client credentials flow to exchange your credentials for an access token.

Use the appropriate endpoint to obtain an access token:

• UK clients: https://auth.fospha.com/oauth2/token
• US clients: https://auth.us.fospha.com/oauth2/token

Include the access token in the Authorization header for all API requests:

NOTE: Replace REGION with your country code; for example, use uk for the United Kingdom or us for the United States.

It is important to remember that:

• An access token expires after 1 hour (3600 seconds)
• Request a new token before the current one expires

Remember to:

• Cache tokens: Store the token in memory and reuse it until expiration
• Handle expiration: Implement automatic token refresh logic
• Secure storage: Never expose client secrets in your code
• Error handling: Handle 401 responses by refreshing the token

The Fospha API uses scopes to control access levels:

• api_data/read : Read access to marketing data (required for queries)

Also, your application will only have access to data that your registered brand permissions allow.

Invalid Client Credentials (400):

• Verify your app_client_id and app_client_secret are correct
• Ensure credentials are URL-encoded in the request body

Unauthorized (401):

• Token has expired, request a new one
• Token is malformed or invalid

Forbidden (403):

• Valid token but insufficient permissions
• Contact Fospha support to review your brand's data access permissions

Token Request Fails:

• Check that you are using application/x-www-form-urlencoded content type
• Verify the OAuth endpoint URL is correct
• Ensure grant_type and scope are included

For OAuth setup issues or credential requests, please contact the technical support at servicedesk.fospha.com

When reporting an issue, please include the following information:

• Your app_client_id (never share your app_client_secret)
• Your fospha_client_id
• The full error message received
• The timestamp (including timezone) when the error occurred
• Any other relevant context (for example, API endpoint and request type)