Skip to content
Riversoft STCP DirectLink API
Security

Security

Riversoft® STCP DirectLink API gives access to the users’ files. For this reason, credentials, tokens and secure links must be protected like passwords. This page gathers the best practices for those who integrate with the API. The product security features are in Riversoft STCP DirectLink security.

Transport

  • Use HTTPS in production and validate the server TLS certificate. Do not disable certificate verification on the client (for example, curl -k).
  • Access the service through the host configured in the environment. Requests with a different host or port may be refused.

Credentials and tokens

  • Do not store passwords, tokens, PINs, TOTP secrets or secure links in source code, versioned files, shell history, logs or support tickets.
  • Keep the integration credentials in a secrets vault or in protected environment variables.
  • Treat the access_token as a password. It is valid for the time given in expires_in; obtain a new token when it expires.
  • Do not reuse production credentials in test environments.

Multi-factor authentication

  • Local login MFA can use a PIN sent by email or SMS, or a TOTP code from an authenticator app. See Local login and MFA.
  • Show the TOTP secret and the QR code only to the user, and only during registration.
  • MFA links are bound to the user and expire. Do not change or reuse them.

Single Sign-On

OAuth 2.0 and SAML 2.0 callbacks are sent by the identity provider. Do not try to build authorization codes, state or SAML assertions manually: these messages are signed and bound to the configured session and provider. See Single Sign-On.

OAuth 2.1 compatibility

The API follows OAuth 2.1 when the password grant is disabled:

  • tokens are obtained through token exchange or Single Sign-On and sent only in the Authorization: Bearer header;
  • in Single Sign-On with OAuth 2.0 and OpenID Connect, the API uses PKCE (S256) and a single-use state on each sign-in, as OAuth 2.1 requires.

The service administrator chooses the accepted authentication methods in the API network service, in the Riversoft Console Portal. If your integration uses the password grant, move to token exchange before it is disabled. See OAuth tokens.

Session

  • The __Host-dirl_session cookie is issued with the Secure, HttpOnly and SameSite=Strict attributes. If your application stores the cookie (for example, in cookies.txt with curl), protect the file as a credential and delete it at the end of the session.
  • End the session with /auth/logout (or with SSO logout) when the integration finishes. Finishing a transfer does not end the session. See Session and logout.

Permissions

  • Use a dedicated user for each integration, with access only to the required mailboxes.
  • Use the impersonation token only in technical integrations, and keep it as a long-lived credential. See OAuth tokens.

Secure links

  • Forward download links only to the authorized recipient.
  • Download links from the listing only work with the user’s own token or session cookie. To deliver a file to third parties, use the shared link.
  • Do not write secure links to logs or include them in public messages.
  • Do not change or reuse MFA, password change or download links. They are bound to the operation and expire.
  • Send the PIN through a channel other than the one used for the link, when your application does this forwarding.
  • The default validity is 24 hours for download links and 180 seconds for PINs; the administrator can change them. Plan the forwarding so that the recipient uses the link within the deadline.

File integrity

On upload, send the expected file hash (h field, SHA-256, in multipart; X-STCPDIRECTLINK-HASH header in the binary body) so that the service can validate the content received. See Send files.

Auditing

Transfers are recorded in the Riversoft STCP DirectLink log. Use the transfer report to follow the integration’s uploads and downloads.

Security checklist

  • HTTPS with certificate validation.
  • Credentials out of code and logs.
  • MFA enabled for local login users.
  • Dedicated integration user, with minimum permissions.
  • Token renewal before or after expiration.
  • Secure links treated as credentials.
  • SHA-256 hash sent on upload, when available.
  • Logout at the end of the session.
  • Transfer report reviewed periodically.
Migration to v2Troubleshooting