Troubleshoot 401 and 403 errors in Cotonity agents that call external APIs, covering API key rotation, token scopes, IP allowlists, and secure credential storage.
Distinguishing 401 from 403 errors
A 401 Unauthorized response means the API could not verify your identity — the credential is missing, malformed, or expired. A 403 Forbidden response means the credential is valid but the authenticated identity lacks permission to perform the requested action. These two error types require different remedies. For 401 errors, focus on the credential itself: verify the API key or token is correctly pasted with no extra whitespace, confirm it has not been rotated or revoked in the external service's dashboard, and ensure the authentication header name matches what the API expects (for example, some APIs use 'X-Api-Key' while others use 'Authorization: Bearer'). For 403 errors, focus on the scope or role assigned to the credential.
Credential storage and retrieval in Cotonity
Cotonity stores API credentials in an encrypted vault accessed through Settings > Credentials. Credentials are referenced in workflow steps by name rather than by value, which means updating a rotated key in the vault automatically propagates the change to every step that references it — you do not need to edit individual steps. If a credential was recently rotated in the external service, open the vault, select the credential, and click 'Update value' to paste the new key. After saving, trigger a manual test run to confirm the updated credential resolves the authentication error.
IP allowlist requirements
Some enterprise APIs restrict access to requests originating from approved IP addresses. If your agents were working previously but began failing after Cotonity migrated infrastructure, the issue may be that Cotonity's outbound IP addresses changed. The current list of Cotonity outbound IP addresses is published on the Security & Compliance page in your account settings. Share this list with the administrator of the external API and ask them to update the allowlist. Cotonity provides a static IP feature on Enterprise plans that assigns a dedicated outbound IP address, eliminating the risk of future disruption from infrastructure changes.
Testing credentials without running a full workflow
To verify a credential is valid without running a full workflow, use the Credential Test tool available in Settings > Credentials. Select any stored credential and click 'Test' to have Cotonity attempt a lightweight authentication check against the target API. The test result shows the HTTP status code and response body, which is often enough to confirm whether the credential is accepted. If the test passes but your workflow step still fails, the issue is likely a permission scope problem rather than the credential itself — check that the API key has the specific permission required for the action the step is attempting to perform.