This API allows you to interact programmatically with SURF Research Cloud. SURF Research Cloud is made up of several 'microservices' that each are responsible for a specific part of the overall service. We provide endpoints to the API on a per microservice basis. You can create an API token from the Research Cloud portal and use it to access various endpoints documented in our Swagger pages for different microservices.

Step 1: Create an API Token

  1. Once logged in to the portal, go to the Profile tab and open the API token section under your user profile.
  2. Click on the “Add API Token" button. Provide a name for your token and write a description. Choose an appropriate expiration date after which the token will not be usable anymore.
  3. Once generated, save your token in a secure place, such as a password manager. Please note that an API token is shown once, so make sure to save it before closing this dialog. This token will be used to authenticate your API requests.

You can create multiple API tokens if necessary.


Step 2: Access and use the API

Now you can use your API token to access endpoints in various SURF Research Cloud microservices. For now we have created two Swagger pages for the microservices 'workspace server' and 'user server'. You can access them via the following links:

Be aware that these pages are continuously being updated to include more functionality. 

Application and wallet API pages are under construction. 

To use the API you need to authorize on each of the Swagger pages by clicking “Authorize” button in the upper right corner of the screen. Copy and paste your SURF Research Cloud API token in the authorisation window and click “authorize”.

Now you have access to the API.

Alternatively, you are also free to use any other method of calling the API endpoints (such as curl commands from a terminal, or using a Python script), as long as you pass the authentication in a similar way as done via Swagger. Using the API via Swagger reveals the corresponding curl command from which you can create your script.

RSC Workspace Server API

This section includes endpoints for workspace-related microservice. For example, you can get the information about your workspaces, pause, resume, delete a workspace, and so on. You can only do these actions to the workspaces that you have access to, e.g. the workspaces that were started in the collaborations that you are part of. 

RSC User Server API

This section includes endpoints for user-related microservice. For example, you can get the information about your collaboration, users in your collaboration, manage secrets, and so on. You can only do these actions to the collaborations that you are part of. 

(this should be in a warning box)

Being a member of a collaboration entitles you to log in to the Research Cloud portal.


Important Security Notice

The API token provided to you is extremely sensitive. Possession of this token grants the holder the same level of access as your login credentials. This means that anyone with this token can perform actions on your behalf within the system, including potentially harmful operations. To protect your account and data, please ensure that this API token is kept secure and never shared. Unauthorized access can lead to significant security breaches and data loss.

Key Points:

  • Treat your API token with the same confidentiality as your password.
  • Do not share your API token with anyone.
  • Store the token securely and avoid exposing it in code or online.
  • If you suspect that your API token has been compromised, immediately regenerate the token and update any applications using it.

Your security is our priority. Protect your API token to safeguard your account.




  • No labels