OAuth integrations allow external systems to connect securely to Altruistiq's API. This article explains how to create integration credentials, rotate secrets when needed, and remove integrations that are no longer required.
Requirements
Permission required: Manage API Keys
This permission is held by Sustainability Administrator, Platform Administrator, Measurement & Reporting Professional, and Supply Chain Engagement Professional roles.
For your IT team: Full API documentation is available at docs.altruistiq.com. The Altruistiq API uses OAuth 2.0 Client Credentials flow as per RFC 6749.
Understanding OAuth credentials
Each OAuth integration has two components:
Component | What it is | How it's used |
Client ID | A public identifier for the integration | Included in API requests to identify which integration is connecting |
Client Secret | A private key known only to your systems | Used to authenticate and obtain access tokens |
The Client ID is visible in the integrations list. The Client Secret is shown only once when you create or rotate the integration — make sure to copy it immediately and store it securely.
View existing integrations
Click your profile icon in the top right corner.
Select Organisation Settings.
Click the Authentication & Security tab.
Scroll down to the OAuth integrations section.
You'll see a table showing all integrations for your organisation, with the Label and Client ID for each.
Create a new integration
Go to Organisation Settings > Authentication & Security.
Scroll down to OAuth integrations.
Click Create integration.
Enter a descriptive label for the integration (for example, "ERP Data Sync" or "Energy Management Upload").
Click Create.
Copy the Client ID and Client Secret immediately and store them securely.
Important: The Client Secret is displayed only once. If you navigate away without copying it, you'll need to rotate the secret to generate a new one.
Result
Your IT team can now use the Client ID and Client Secret to authenticate with the Altruistiq API. They'll exchange these credentials for an access token, which is then used for API requests. The token endpoint is: https://app.altruistiq.com/api/public/v1/oauth2/token
Rotate a Client Secret
Rotate the secret if you believe it may have been compromised, when team members with access leave the organisation, or as part of regular security hygiene.
Go to Organisation Settings > Authentication & Security.
Scroll down to OAuth integrations.
Find the integration you want to update.
Click the menu icon (⋮) on the right side of that row.
Select Rotate secret.
Copy the new Client Secret immediately and store it securely.
Update the secret in your connected systems.
Important: After rotating, the old secret stops working immediately. Coordinate with your IT team to update connected systems promptly to avoid interruption.
Delete an integration
Delete an integration when it's no longer needed — for example, when decommissioning an automated data flow or replacing one integration with another.
Go to Organisation Settings > Authentication & Security.
Scroll down to OAuth integrations.
Find the integration you want to remove.
Click the menu icon (⋮) on the right side of that row.
Select Delete secret.
Confirm the deletion.
⚠️ Warning: Deleting an integration immediately revokes access. Any systems using those credentials will no longer be able to connect. Make sure the integration is genuinely no longer needed before deleting.
Tips
Security best practices
Create separate integrations for different purposes. If you have multiple data flows (for example, energy data from one system and procurement data from another), create a separate integration for each. This makes it easier to rotate or revoke access for one connection without affecting others.
Use descriptive labels. Clear naming helps you identify which integration to update or remove when needed.
Rotate secrets periodically. Even without a suspected compromise, rotating secrets annually is good security practice.
Review integrations regularly. Check the integrations list periodically and remove any that are no longer in use.
Store secrets securely. Client Secrets should be stored in a secure location such as a secrets manager or encrypted credential store — not in plain text files, emails, or shared documents.
Trips for naming integrations
Use descriptive labels that identify both the purpose and the source system. This makes it easy to manage integrations as your automation grows. Good examples include "SAP Procurement Data Upload", "Schneider Energy Management Sync", "Production System – Monthly Volume Data", and "PACT Export – Customer Portal". Avoid generic names like "Test" or "API Key 1" — these become confusing when you have multiple integrations.
Troubleshooting
I didn't copy the secret when creating the integration You'll need to rotate the secret to generate a new one. The original secret cannot be retrieved.
The integration stopped working after I rotated the secret The old secret is invalidated immediately when you rotate. Update the secret in your connected system to restore the connection.
I don't see the OAuth integrations section Check that you have the Manage API Keys permission. If you don't see Organisation Settings in the menu, you may not have access to this area.