How to Publish a REST API Using the Standalone Security Server?

The Standalone Security Server is a special version of Security Server that is ready-to-use in minutes without the normal Security Server installation, configuration and registration process. It is meant for testing purposes in X-Road service development and it cannot communicate with other Security Servers.

In addition, the Standalone Security Server does not require connection to the Central Server, OCSP service or time-stamping service. Therefore, the Standalone Security Server can be set up in minutes and once it has been downloaded it does not even require an internet connection. It is ideal for testing purposes in service development or for someone who’s interested in giving a quick try.

It is possible to add new services on the Standalone Security Server and invoke the services using the same Security Server. It comes with two pre-configured subsystems – one for providing and another for consuming services. Subsystems represent information systems that are connected to X-Road as service consumers, service providers or both. A single Security Server can have unlimited number of subsystems and they can be owned by different member organisations. More information about members and subsystems is available here.

Message flow between the service consumer and service provider when using the Standalone Security Server.

1. Start the Standalone Security Server Docker container

Run the latest version of the Standalone Security Server Docker image.
The command publishes the container ports 4000 and 8080 to localhost.

When you run the command below on your computer for the first time, Docker will download the niis/xroad-security-server-standalone image from Docker Hub. This may take some time depending on the speed of your internet connection.

docker run -d \
  --name standalone \
  --hostname ss \
  -p 127.0.0.1:4000:4000 \
  -p 127.0.0.1:8080:8080 \
  niis/xroad-security-server-standalone:noble-7.7.0

The configuration in the image expects that --hostname ss is used when spinning up a container. Please do not omit the hostname parameter or use other value than ss.

2. Access the Security Server admin UI

Wait for a couple of minutes for the Security Server admin UI to become available at:
- https://localhost:4000
When accessing the UI for the first time, the self-signed certificate from the server needs to be accepted.

Select Advanced and then Accept the Risk and Continue.

Login to the Security Server admin UI. The username is xrd and the password is secret.

3. Configure the REST API

Click the subsystem name TestService to open its details.

Go to the Services tab.

Click Add REST.

In the Add REST service view:
- Select OpenAPI3 Description as the URL type.
- Enter the OpenAPI3 specification URL in the URL field (e.g., https://d14r9k0rinox9f.cloudfront.net/yaml/x-road-stats.yaml).
- Enter the Service Code (e.g., TestAPI).
Click Add.

4. Enable and Verify the Service

The Security Server fetches and parses the OpenAPI description.
The service is added to the Services list but is disabled by default.
Enable it by toggling the switch on the right side of the service row.

A notification “Service description enabled” will appear.
Click the “>” symbol on the left to expand service details.

Click the Service Code to open the full details.

5. Review and Edit the Service URL

The Service URL is extracted from the OpenAPI servers.url field.
This URL is where the Security Server forwards incoming requests.
If the parsed value is incorrect, it can be manually edited.

6. TLS Certificate Handling

More information about the different TLS certificate verification configuration options is available in the Security Server User Guide.

By default, Verify TLS certificate is enabled.
- This means the Security Server verifies the API’s TLS certificate.
- To enable verification, upload the API's certificate in the Internal servers → Information System TLS certificate section.
If you prefer not to verify the TLS certificate:
- Uncheck Verify TLS certificate.
- In this case, no certificate upload is needed.
Click Save to apply the configuration.

7. Configure Access Rights

More information about defining access rights is available in the Security Server User Guide.

In the Access Rights section, click Add subjects.
Click Search without entering any criteria to list all registered subsystems.
Select the TestClient subsystem and click Add selected.

The selected subsystems now appear under Access Rights. It has access to all the endpoints that belong to the REST API.

Alternatively, instead of giving access to all the API endpoints, it’s possible to define access rights on an endpoint level. Open the Endpoints tab to view the list of endpoints parsed from the OpenAPI description and define access to them separately.

Click Close to return to the Services view.

7. Test the Service

Send a curl test request using the TestClient subsystem as a service client. For example:

curl -X GET \
  -H 'X-Road-Client: CS/ORG/1111/TestClient' \
  'http://localhost:8080/r1/CS/ORG/1111/TestService/TestAPI/instances'

Alternatively, you can run curl in a container if you don’t have it installed locally:

docker run --rm curlimages/curl:latest -X GET \
  -H 'X-Road-Client: CS/ORG/1111/TestClient' \
  'http://localhost:8080/r1/CS/ORG/1111/TestService/TestAPI/instances'

The first request might be a bit slow, but the following requests will be faster.

Feel free to use your preferred HTTP client (e.g., Postman) to send requests to the Standalone Security Server. Just add the X-Road-Client: CS/ORG/1111/TestClient HTTP header to the request and use http://localhost:8080/r1/CS/ORG/1111/TestService/TestAPI/instances as the target URL.

8. How to construct the service URL on the client Security Server (Example)?

For example, the base path of the REST API is https://api.stats.x-road.global/v1, and the API exposes an endpoint at /instances. When invoking the endpoint directly, the full request URL is:

https://api.stats.x-road.global/v1/instances

However, when invoking the same endpoint over X-Road, you must replace the REST API's base path with the client Security Server's REST interface URL and append the X-Road service identifier as path parameters, following this format:

http://<CLIENT_SECURITY_SERVER_HOST>:8080/r1/<INSTANCE_IDENTIFIER>/<MEMBER_CLASS>/<MEMBER_CODE>/<SUBSYSTEM_CODE>/<SERVICE_CODE>/<REST_API_ENDPOINT>

For example, the direct API endpoint:

https://api.stats.x-road.global/v1/instances

Becomes the following URL when invoked over X-Road when the service identifier is TEST/GOV/1234/TestService/TestAPI:

http://<CLIENT_SECURITY_SERVER_HOST>:8080/r1/TEST/GOV/1234/TestService/TestAPI/instances