Conviva API Authentication

Conviva API system accepts only API client-based credentials. Generate API credentials in the Pulse API Management page to get a pair of {id} and {secret}.

Note: Do not use your Pulse user-based credentials for any API request.

Keep your credentials secure: Do not put your {id}, {secret}, or their Base64 value directly in a command. Anything on the command line is saved to your shell history, is visible to other users in the process list, and often ends up in CI logs. Base64 is encoding, not encryption, so it is no safer than plain text. Store credentials in a netrc file or your CI secret store, and rotate them immediately if they are ever exposed.

Recommended: use a netrc file with cURL

A netrc file keeps your credentials off the command line and works the same way across Windows, macOS, and Linux. cURL reads it automatically and builds the authentication header for you.

macOS and Linux: create ~/.netrc, then run chmod 600 ~/.netrc so only you can read it.
Windows: create %USERPROFILE%\_netrc (underscore, no leading dot).
Or keep it in your project: save ./.netrc and point cURL at it with --netrc-file ./.netrc. Add .netrc to your .gitignore so it is never committed to version control.

Add the following to the file, replacing the placeholders with your API credential:

Copy

machine api.conviva.com
login YOUR_CLIENT_ID
password YOUR_CLIENT_SECRET

Then call the API with the --netrc option. cURL builds the Authorization header for you:

Copy

curl --netrc "https://api.conviva.com/insights/3.0/metrics/attempts?days=1"

Environment-variable alternative

If you prefer to keep credentials in environment variables, pass them to cURL with -u and let cURL build the header. The syntax depends on your shell:

bash or zsh: curl -u "$CONVIVA_CLIENT_ID:$CONVIVA_CLIENT_SECRET" ...
PowerShell: curl.exe -u "${env:CONVIVA_CLIENT_ID}:${env:CONVIVA_CLIENT_SECRET}" ... (use curl.exe; plain curl is an alias for Invoke-WebRequest).
Command Prompt: curl -u "%CONVIVA_CLIENT_ID%:%CONVIVA_CLIENT_SECRET%" ...

How Basic authentication works (background)

Under the hood, the Conviva API uses HTTP's Authorization Basic scheme. You do not need to build this yourself: cURL constructs the header for you from --netrc or -u. For reference, the scheme works as follows:

Concatenate the API credential's {id} and {secret} with a single colon : character, like {id}:{secret}.
Use Base64 encoding scheme to encode the concatenated string.
Append Basic: in front of the encoded string, and place it in the Authorization request header.

For example:

Copy

const [clientId, clientSecret] = ['abcdefghij', 'z1y2x3w4v5u6t7s8r9q0p']; // API credential information
const concatenatedCredential = `${clientId}:${clientSecret}`; // concatenate with ':'
const base64EncodedCredential = Buffer.from(concatenatedCredential).toString('base64'); // base64 encoding
const httpAuthorizationHeader = `Basic ${base64EncodedCredential}`; // HTTP Authorization header value: 'Basic YWJjZGVmZ2hpajp6MXkyeDN3NHY1dTZ0N3M4cjlxMHA='

You do not need to run these steps yourself. When you call the API with --netrc or -u, cURL builds this Authorization header for you and keeps your credentials off the command line.

Conviva API server accepts only the HTTPS secure transport communication scheme. All message content is encrypted with the HTTPS transport protocol.

Contact Conviva Support (support@conviva.com) with any questions about account credentials.