Concepts

Riversoft® STCP Gemini API acts on behalf of the Riversoft Console Portal operators: each authenticated call uses the operator’s permissions to configure, administer, supervise and query the Riversoft STCP Gemini and Riversoft STCP DirectLink environment. This page gathers what you need to know before you integrate.

The API does not transfer files: for that, use the Riversoft STCP DirectLink API.

Base URL and versioning

https://{host}:{port}

The {host} and {port} are the ones configured in the general section of the API config.json (sample port: 33070). See API configuration.

Each route group has its own version in the path, for example /stcpcore/v2, /reports/v2, /disconnect/api/v3 and /auth/api/v1. The product version is returned by GET /info/version.

Authentication methods

All methods result in a Bearer token, used on protected routes.

See how to choose and use each method in Authentication.

Credentials on protected routes

Send the token in the Authorization header:

Authorization: Bearer <access_token>

Without a token, or with an invalid or expired token, the API responds 401, in text (Unauthorized). With a valid token but without the permission required by the route, it responds 403. The /info and sign-in routes are public. Details in Session and logout.

Integration flow

    flowchart TD
    A[Application] --> B{Authentication method}
    B -->|Local sign-in or LDAP| C["POST /oauth/v2/token"]
    C --> D{2FA enabled?}
    D -->|Yes| E["POST /oauth/v2/token/mfa/challengeID"]
    D -->|No| F[Bearer token]
    E --> F
    B -->|Password grant| G["POST /oauth/token"]
    G --> F
    B -->|SSO| H[Redirect to the provider]
    H --> I[SAML 2.0 or OAuth 2.0 return]
    I --> F
    F --> K{Operation}
    K -->|Configure| L["/stcpcore/v2"]
    K -->|Administer| M["/stcpadmin/v2"]
    K -->|Supervise| N["/stcpadminsvc/v2"]
    K -->|Query| O["/reports/v2"]
    L --> Q["DELETE /disconnect/api/v3/logout"]
    M --> Q
    N --> Q
    O --> Q
  

REST model

Resources are exposed through endpoints and handled with HTTP methods according to the operation.

Resources

All resources used by the Riversoft Console Portal are available for integration. See the endpoint catalog and the OpenAPI specification.

Operators and permissions

Calls are made on behalf of a Riversoft Console Portal operator. Every call by the operator is recorded and can be queried in the operator report.

Permissions come from the operator’s groups. Each group defines:

• the permissions on each resource;
• the relations: instances, operators and users that the group members can access. The value [0] gives access to all.

When the operator belongs to more than one group, the permissions are added up. The stcpadmin operator has full access, regardless of groups. The issued token carries the permissions in the scope field, organized into four resource groups:

The permission required by each endpoint is stated in the OpenAPI specification.

Configuration entities

Configuration and administration entities follow the same envelope: ID, NAME, DESCRIPTION, CONFIG_TXT (the configuration, in JSON), CREATED, MODIFIED and EXTRA_TXT. Entities of an instance (users, network services, schedules, global file types and routings) also have INSTANCE_ID; user file types, USER_ID.

• On update (PUT), the CONFIG_TXT sent replaces the stored one entirely: get the entity, change the fields and send the complete object.
• Passwords and secrets are returned masked in queries. Sending the masked value back keeps the stored one.
• The operator only sees the entities related to their groups.

See CONFIG_TXT structure.

Data formats

Dates: the report start and end filters use Unix timestamps in milliseconds and are required. The DATAHORA response field uses the ISO 8601 format (for example, 2025-12-20T19:54:17-03:00).

Responses and errors

Errors are returned in JSON, with the entity type, the error and the description:

{
  "field": "instance",
  "error": "instance error",
  "error_description": "NAME is required"
}

The sign-in routes use only error and error_description. See Response codes.

Pagination

Reports return the records in data and, when there are more results, the next page URI in next. Repeat the call with the next URI until it comes back empty. The limit parameter sets the number per page: default 100, maximum 15000. Audit reports return the whole period, without pagination.