OAuth2 Client Credentials Flow

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

Prerequisites

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.

Step 1: Obtain an Access Token

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

Request

# Example for UK clients
curl -X POST https://auth.fospha.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --user "<YOUR_APP_CLIENT_ID>:<YOUR_APP_CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=api_data/read"

# Example for US clients
curl -X POST https://auth.us.fospha.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --user "<YOUR_APP_CLIENT_ID>:<YOUR_APP_CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=api_data/read"

Response

{
  "access_token": "<YOUR_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api_data/read"
}

Step 2: Use the Access Token

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

curl -X POST https://api.<REGION>.fospha.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "query": "{ marketingDataReadiness(clientId: \"YOUR_FOSPHA_CLIENT_ID\") { status lastProcessedAt } }"
  }'

note

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

Token Management

Token Expiration

It is important to remember that:

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

Best Practices

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

Scopes and Permissions

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.

Troubleshooting

Common Issues

Invalid Client Credentials (400):

• Verify your app_client_id and app_client_secret are correct
• Ensure your app_client_id and app_client_secret are passed via HTTP Basic auth (the --user flag) with no stray whitespace or newlines

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

Support

For OAuth setup issues or credential requests, please visit our support portal at servicedesk.fospha.com.

When reporting an issue, please include:

• 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)