Concepts

Riversoft® STCP DirectLink API acts on behalf of the Riversoft STCP DirectLink transfer users: each authenticated call uses the user’s mailbox to send, receive and share files. This page gathers what you need to know before you integrate. For the mailbox, transfer rules and routing, see the Riversoft STCP DirectLink concepts.

Base URL and host

All calls use the /directlink/v2 version prefix:

https://{host}/directlink/v2

Use exactly the host configured for the service, provided by the environment administrator. The API can reject the request (HTTP 403) when the host or port sent by the client does not match the configured address. For this reason, do not access the service by IP address or by an alternative name.

Versioning

The API version is part of the path (v2) and is returned in the apiver field of responses, together with the product version (for example, v2 (9.0.1)). This documentation describes version v2, available from Riversoft STCP DirectLink 9.0.1. Version v1 is no longer served; see Migration from v1 to v2.

Authentication methods

The API offers four ways to authenticate a user. All of them result in a session credential that you use on protected routes.

To choose and use each method, see Authentication.

Credentials on protected routes

Protected routes accept the session credential in two ways:

When you send both, the Authorization header takes precedence. Details in Session and logout.

Integration flow

    flowchart TD
    A[Client] --> B{Authentication method}
    B -->|Local login| C[POST /auth/login with Basic]
    C --> D{MFA enabled?}
    D -->|Yes| E[Validate challenge at /auth/mfa]
    D -->|No| F[Authenticated session]
    E --> F
    B -->|OAuth 2.0| G[POST /auth/token or /oauth2/token]
    G --> F
    B -->|SSO| H[Redirect to the provider]
    H --> I[OAuth 2.0 or SAML 2.0 callback]
    I --> F
    F --> K{Operation}
    K -->|Send| L[POST /upload]
    K -->|Receive| M[GET /download/list]
    M --> N[GET returned linkURL]
    K -->|Query| O[GET /report]
    L --> Q[POST /auth/logout or SSO logout]
    N --> Q
    O --> Q
  

Downloads through a shared link follow their own validation and do not require the recipient to start a session. See Shared links.

Secure links

Some responses include URLs issued by the service, usually in the linkURL field:

Secure links:

• are signed and bound to the operation, user, and file for which they were created;
• have an expiration time set by the administrator (by default, 24 hours for download links and 180 seconds for PINs) and can require a PIN;
• stop working when the file is no longer available.

Use each link exactly as received. Do not remove, edit, or manually build its parameters, and treat it as a credential.

Access rules

A valid credential does not guarantee that every operation is authorized. Each operation is also validated against the rules configured for the user and the environment, for example:

• upload or download service enabled for the user;
• user unlocked and authorized;
• allowed access time or time window;
• size limits, file types, and name filters;
• concurrent session limit and resource availability;
• success of the preprocessing steps configured in the environment.

When one of these rules blocks the operation, the API responds with an error (usually 403). Ask the service administrator which rules apply to your user.

Data formats

Dates and times: the timestamp field of the health check uses RFC 3339 in UTC; the modified field of listings uses Unix time in milliseconds. The environment defines the format of the other date fields (such as time).

Response envelope

Most operations respond with a JSON object with common fields:

{
  "status": 0,
  "description": "<description returned by the API>",
  "apiver": "v2 (9.0.1)",
  "user": "<user>",
  "time": "<date and time>"
}

Each operation adds its own fields. The token endpoints follow the OAuth 2.0 format and do not use this envelope. See Data models.

The error body format varies between endpoints: handle the HTTP status first and, when present, use the returned description. See Codes and events.