Troubleshooting

Symptom: an integration that worked on version 8 now receives 400 on /upload, /download/list or /report.

Probable cause: the call sends Authorization: Basic. Starting with version 9, these routes accept only a Bearer token.

Solution: obtain a token from POST /oauth2/token (or at sign-in) and send Authorization: Bearer <access_token>. See API authentication.

Symptom: the API returns 401.

Probable cause: nonexistent user, wrong password, or a Bearer token that has expired or has an invalid signature, issuer or audience.

Solution: check the user name and password registered on the STCP server. Obtain a new token from /oauth2/token; it expires after expires_in seconds.

Symptom: exchanging the service portal’s JWT for a Riversoft® STCP DirectLink token is rejected.

Probable cause: the JWT signature does not match the key registered for the provider, iss or aud do not match the configuration, the token has expired, or the user in the claims does not exist on the STCP server.

Solution: check that the token was signed with the private key matching the registered key and that kid and alg match. Check the identifier sent in provider (or in the X-STCPDIRECTLINK-JWT-ISSUER header), the server clocks and the user. See Trusted JWT.

Symptom: POST /oauth2/token returns 400.

Probable cause: the body is not application/x-www-form-urlencoded, grant_type is missing or, on token exchange, subject_token_type is not urn:ietf:params:oauth:token-type:jwt.

Solution: send the form with the Content-Type: application/x-www-form-urlencoded header. For the password grant: grant_type=password&username=<user>&password=<password>. The response includes error and error_description with the reason.

Symptom: the token is accepted, but the call returns 403.

Probable cause: an access rule blocked the operation: the user’s connection is blocked, the call is outside the time window, the service is disabled, a file filter applies, the session limit was reached, or the URL host differs from the one configured for the API.

Solution: use exactly the host provided by the administrator and ask them to check the user’s rules on the STCP server.

Symptom: sign-in, first access or password recovery returns 400, 403 or 503.

Probable cause: 400 means the CF-Turnstile-Response header was not sent or is invalid; 403, that the token was rejected (invalid, expired or already used); 503, that the server could not validate the token with Cloudflare.

Solution: generate a new widget token for each attempt (it is single-use and expires in 300 seconds). On 503, try again; if it persists, the administrator must check the server’s outbound HTTPS access to challenges.cloudflare.com.

Symptom: GET /auth/firstaccess returns 403.

Probable cause: the user has already completed the first access.

Solution: use Forgot password to reset the password.

Symptom: a file already downloaded does not appear in /download/list.

Probable cause: after the download, the file moves to the backup area.

Solution: query /download/list/backup and download it again through the returned linkURL, while the retention policy allows.

Symptom: the list returns at most 100 files.

Probable cause: the list is paginated.

Solution: increment the page parameter starting at 0 until you receive an empty list.

Symptom: the /portal address returns 404 or the portal does not load its configuration.

Probable cause: the portal config.json was not created from example-config.json, or the static pages path of the API service in the instance is not the default.

Solution: create config.json from the template (see Riversoft STCP DirectLink Portal configuration) and check, in the instance API network service, that the static pages path is /usr/local/stcpdirectlink/static, with no trailing slash.