Skip to content
Riversoft STCP Gemini API
Security

Security

Riversoft® STCP Gemini API gives access to the configuration, administration and supervision of the environment. For this reason, operator credentials and tokens must be protected like administration passwords. This page gathers the best practices for those who integrate with the API. The product security features (TLS, SSO, MFA and password policies) are in Riversoft STCP Gemini security.

Transport

  • Publish the API over HTTPS only: enable ssl in the API config.json, with a valid certificate. See API configuration.
  • Use the -ns option (no TLS) only in isolated test environments.
  • Validate the server certificate on the client. Do not disable verification (for example, curl -k).
  • Allow access to the API port only from the networks and systems that need it.

Credentials and tokens

  • Do not store passwords, tokens or TOTP secrets 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 60 minutes by default (session_duration, up to 720 minutes); obtain a new token when it expires.
  • The token is signed with the API api_secret: use a strong, private value unique to the environment.
  • Do not reuse production credentials in test environments.

Two-factor authentication

  • Enable operator 2FA in the API registration (enable2FA). With it, use the sign-in at POST /oauth/v2/token: the POST /oauth/token route does not apply 2FA. See Local sign-in and 2FA.
  • Show the TOTP secret and the QR code only to the operator, and only on the first access.
  • The challenge accepts three wrong codes; on the fourth, the operator is locked.
  • If the operator loses the authenticator app, reset their 2FA through maintenance. A new secret is generated at the next sign-in.

Single Sign-On

  • SAML 2.0 and OAuth 2.0 returns are sent by the identity provider. Do not build authorization codes, state or SAML assertions manually.
  • In SSO, the token arrives in the redirect query string. Read it as soon as the page loads, remove it from the URL and do not write it to logs.
  • In SSO sign-in, the 2FA is the one required by the identity provider, not the API one.

See Single Sign-On.

Session

  • Keep the token in memory or in session storage; do not store it in permanent browser storage.
  • End the session with DELETE /disconnect/api/v3/logout when the integration finishes. After an SSO sign-in, redirect the browser to the address received in redirect, when present. See Session and logout.

Permissions

  • Use a dedicated operator for each integration, in groups with only the required permissions (0 no access, 1 read, 15 read and write).
  • In the group relations, limit the instances, users and operators that the integration can see.
  • The stcpadmin operator has full access. Change the default password on the first access and do not use it in integrations.

See Concepts and architecture.

Sensitive data

  • CONFIG_TXT holds the entities’ passwords and secrets. The API returns them masked; do not remove the mask and do not write full responses to logs.
  • When updating an entity, send the masked value back to keep the stored one. Send a new value only when you want to change it.
  • The supervision credentials in the API registration and the database credentials are sensitive data.
  • The key used to encrypt these passwords in the database is api_secret, which must be the same in the other modules of the environment. See Password encryption key.

Auditing

Every call made by an operator is recorded with operator, method, path and HTTP status. Use the operator report and the audit reports to follow accesses and changes.

Security checklist

  • API published over HTTPS only, with certificate validation.
  • Credentials and tokens out of code and logs.
  • Strong and protected api_secret.
  • 2FA enabled for operators, with sign-in at POST /oauth/v2/token.
  • stcpadmin default password changed, and stcpadmin kept out of integrations.
  • Dedicated operator with minimum permissions for each integration.
  • SSO token removed from the URL after it is read.
  • Responses with CONFIG_TXT kept out of logs.
  • Logout at the end of the session.
  • Operator and audit reports reviewed periodically.
Quick startTroubleshooting