Management resources
Related guide: Manage resources. The full contract of each endpoint is in the OpenAPI specification.
Conventions
| Item | Rule |
|---|---|
| Identification | Entities are accessed by ID in the path: /id/{ID}. |
| Body | JSON, with the Content-Type: application/json header exactly like this, without charset. |
| Creation | POST on the collection path, with the entity without the ID field. |
| Update | PUT on the entity path, with the complete entity. The CONFIG_TXT sent replaces the stored one entirely. |
| Sensitive fields | Passwords and secrets are returned masked (****). When updating, send the masked value to keep the stored value. |
| Access | The operator sees only the entities related to their groups. |
Entity format
Configuration entities share the same envelope:
| Field | Description |
|---|---|
ID | Identifier. Omitted on creation. |
INSTANCE_ID or USER_ID | Owner entity (instance or user), when applicable. |
NAME | Name. Required. |
DESCRIPTION | Description. |
CONFIG_TXT | Entity configuration, in the same format used by the Riversoft Console Portal. |
CREATED, MODIFIED | Creation and last modification dates. |
EXTRA_TXT | Additional data. |
Tip
The simplest way to create a new entity is to get a similar existing one, change NAME and the required fields, and send it without ID.
CONFIG_TXT structure
CONFIG_TXT is a JSON object, divided into sections. All of them have the Entity section, with the entity type (Name) and the structure version (Version = 2). The fields of each section are in the Cfg* schemas of the OpenAPI specification.
| Entity | Schema | Sections |
|---|---|---|
| Instance | CfgInstance | Authentication (user authentication, MFA, password policies and LDAP), Log (log database and filters), Startup (service, directories, sessions, external lock and SSO providers) |
| User | CfgUser | General, Token, Net1 and Net2 (main and alternative network), and one section per protocol: OFTP, SFTP, FTP, S3, AzBlob, OciBlob, GcpBlob, WhatsApp, AS2, WebHook |
| Network service | CfgService | Service, Net1, and one section per type: OFTP, SFTP, API, WhatsApp, AS2, WebHook, Monitor |
| Schedule | CfgSchedule | Schedule |
| File type (global or user) | CfgFileType | FileConf |
| Routing | CfgRouting | Rules.General (scan) and Rules.FileMatching[] (rules, with General, Filename, Copy and Backup) |
| Operator | — | Operator, Relations.Groups |
| Group | — | Permissions, Relations |
| API registration | — | Monitor, passwordPolicies, ssoProviders, enable2FA, TLS and SSO |
Things to watch when updating:
PUTreplaces the wholeCONFIG_TXT. Omitted fields go back to empty or zero. Get the entity, change the fields and send the complete object.- Unknown fields are ignored without error. Check the field names in the schema.
- Sensitive fields are returned masked. Sending the masked value back keeps the stored value.
Note
The schemas match the stcpcfgifacetypes-go v1.3.2 configuration module, used by Riversoft STCP Gemini API 3.10.0.
Coded values
Some CONFIG_TXT fields use codes. When the field accepts a combination, the value is the sum of the codes.
| Field | Values |
|---|---|
User: General.TransferProtocol | 0 disabled, 1 OFTP, 2 SFTP, 4 Amazon S3, 5 Azure Blob Storage, 6 OCI Object Storage, 7 Google Cloud Storage, 8 WhatsApp, 9 FTP, 10 AS2, 11 Webhook |
User: General.TransferProtocolIn | Protocols accepted in the inbound connection: sum of 2^protocol. Example: OFTP and SFTP = 2 + 4 = 6 |
User: General.AuthMFAMethod | 0 follows the instance; 128 disables MFA for the user |
User: InitMode | Both, Initiator, Responder |
User: Mode | Both, Sender, Receiver |
User: *ProxyType | 0 SOCKS4, 1 SOCKS5, 2 HTTP, 3 HTTPS, 4 FTP |
User: AS2.MDNOptions (sum) | 1 enabled, 2 signed, 4 asynchronous, 8 encrypted |
User: SendDocumentOptions and RequiredDocumentOptions (sum) | 1 signed (multipart), 2 signed, 4 encrypted, 8 compressed |
User: AuthMode (AS2 and Webhook) | 0 none, 1 Basic, 2 Bearer |
User: Net1.WhatsAppDownloadMode | 0 Meta document ID, 1 Meta link, 2 secure link without password, 3 secure link with password |
Service: Service.ServiceType | 0 OFTP, 1 API, 2 supervision (DirectLink), 3 SFTP, 4 supervision (Gemini), 5 WhatsApp, 6 AS2, 7 Webhook |
Service: API.AuthMode (sum) | 1 Basic, 2 Bearer, 4 token exchange (JWT), 8 password grant. 0 accepts all. The Bearer token is always required on routes that are not authentication routes. |
Schedule: Schedule.Type (sum) | 1 receiving, 2 sending, 4 command, 8 optimized sending, 128 Riversoft STCP DirectLink |
Schedule: Schedule.Mode | 0 date, 1 date with interval, 2 interval |
File type: FileConf.FileMatch | 0 default, 1 prefix/suffix, 2 file name, 3 regular expression |
File type: FileConf.FileDirection | 0 both, 1 sending disabled, 2 receiving disabled |
Instance: Authentication.AuthType | 0 operating system, 1 STCP, 2 RSA SecurID, 3 LDAP |
Instance: Authentication.AuthMFAMethod | 0 disabled, 1 authenticator app (TOTP), 2 code by email, 3 code by SMS |
Instance: Authentication.AuthPolicyPswdComplex and API registration: passwordPolicies.complexity (sum) | 1 lowercase, 2 uppercase, 4 digit, 8 symbol (15 = all) |
Instance: Startup.ExternalLockType | in-memory, filesystem, redis |
Instance: Startup.OSType | LINUX, WINNT, WIN32, MACOS |
SSO provider: ssoType | oauth2, saml2, jwt, ldap |
Responses
| Operation | 200 response |
|---|---|
Query (GET) | {"status": 200, "field": "<entity>", "data": [ ... ]} |
Creation and update (POST, PUT) | {"data": "<entity name>", "field": "<entity>"} |
Deletion (DELETE) | {"data": "<Entity> deleted with success", "field": "<entity>"} |
Errors follow the format described in Response codes.
Configuration (/stcpcore/v2)
| Resource | Path | Permission |
|---|---|---|
| Instances | /instances | stcpcore.instance |
| Instances and their users | /instances/members | stcpcore.instance = 15 |
| Users | /instances/id/{instanceID}/users | stcpcore.user |
| Network services | /instances/id/{instanceID}/services | stcpcore.service |
| Schedules | /instances/id/{instanceID}/schedules | stcpcore.schedule |
| Global file types | /instances/id/{instanceID}/ftypesglobal | stcpcore.filetypeglobal |
| User file types | /instances/id/{instanceID}/users/id/{userID}/filetypes | stcpcore.filetype |
| Routings (Riversoft STCP Gemini Rename) | /instances/id/{instanceID}/routing | stcpcore.routing |
File types also have GET .../check?filename=<name>, which returns the types whose regular expression matches the given name. Routings can be queried by name at GET .../routing/name/{name}.
Administration (/stcpadmin/v2)
| Resource | Path | Permission |
|---|---|---|
| Operators | /operators | stcpadmin.operator |
| Own profile and password | /operators/me, /operators/me/password | stcpadmin.operator |
| Groups and permissions | /groups, /groups/id/{groupID}/operators | stcpadmin.group |
| API registration | /settings | stcpadmin.setting |
| Password policies | /api/policies | stcpadmin.operator = 15 |
| Error and event codes | /error_events | stcpadmin.error_event |
The API registration corresponds to API/Supervision in the Riversoft Console Portal. It holds TLS, address and port, 2FA enablement, password policies, SSO providers and the supervision nodes (instance, node name, credential, host, port, TLS and certificate). At startup, the API loads the registration whose name matches the rest_name in its config.json.
Supervision (/stcpadminsvc/v2/supervision/stcpmon)
The API sends the commands to the supervision services of Riversoft STCP Gemini Server and Riversoft STCP DirectLink registered in the API registration. All use POST with the body {"Instance": "...", "Node": "...", "Name": "...", "Level": "..."}; without Node, the command goes to every node of the instance.
| Path | Command | Permission (stcpadminsvc) |
|---|---|---|
/monitor/nodes | Lists the enabled supervision nodes. | mon_console_info |
/instance/info | Instance information. | mon_inst_info |
/instance/restart | Restarts the instance. | mon_inst_restart |
/instance/debug | Changes the debug level (Level). | main_set_level |
/instance/console | Console messages. | mon_console_info |
/user/info | User information. | mon_user_info |
/user/start | Starts an outbound connection with the user (Name). | mon_user_start_conn |
/user/stop | Cancels the user’s connection (Name). | mon_user_canc_conn |
/user/create_folder | Creates the user’s directory structure (Name). | main_user_create_folders |
/schedule/start | Runs the schedule (Name) right away. | mon_sched_exec |
/service/info | Network service information. | mon_inst_serv |
/sandbox, /keystore | Lists (GET), sends (POST, Base64 content) and deletes (DELETE) mailbox or keystore files. | mon_sandbox_file_management, mon_keystore_file_management |
The response carries, in data, the response of each node: {"Instance": "...", "Nodename": "...", "Data": [ ... ]}.
Maintenance (/stcpadminsvc/v2/supervision/stcpauth)
All use POST with the body {"Instance": "...", "Name": "...", "NewPassword": "...", "CurrentPassword": "..."}. For operators, Instance is not used.
| Path | Operation |
|---|---|
/reset/user/password, /reset/operator/password | Sets a new password, checked against the password policies. |
/change/user/password, /change/operator/password | Changes the password, sending the current one in CurrentPassword. |
/reset/user/lock, /reset/operator/lock | Removes the sign-in failure lock. |
/reset/user/hash | Recreates the user’s authentication hash. |
/reset/user/2fa, /reset/operator/2fa | Deletes the TOTP secret; a new one is generated at the next sign-in. |