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 SURF Research Cloud portal and use it to access various endpoints documented in our Swagger pages for different microservices.

This is a pilot release, and we are monitoring usage to improve the service. The API uptime aligns with the uptime of SURF Research Cloud, which can be found in the DVO contract signed by SURF and your institution. The Rate Limit is currently set at 1000 requests per 60 seconds per API key, but this may change in the future. We use queue management to prevent excessive usage. API support is available only for members of the User Support Group due to the nature of their subscription. Other users will not receive direct API support. 

How to Use the SRC API

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.

SRC 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. 

SRC 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. 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.


Rate Limits

To ensure fair usage and maintain system stability, we enforce rate limits on API requests. Understanding these limits will help you design your API integration efficiently and avoid potential disruptions.

Current Rate Limit Policy

  • Request Limit: Each user can make up to 1000 requests per 60 seconds per API key.
  • Reset Period: The rate limit resets every 60 seconds, allowing you to make another 1000 requests in the next period.
  • Quota Limit: There is no overall quota limit, meaning you are not restricted to a maximum number of requests over a day, week, or month.
  • Quota Renewal: Although the system theoretically renews quotas every 3600 seconds (1 hour), this setting is irrelevant since there is no upper quota restriction (quota_max: -1).

Queue Monitoring and System Load

Our API handles task processing through a queue-based system, which ensures that tasks are processed efficiently without overloading the backend. Below, we explain how this system works and what users should expect.

How the Queue Works:

  • Task Submission: When you request a workspace operation through the API, your task is placed in a queue.
  • Task Processing: The queue processes tasks on a first-come, first-served basis, depending on available system resources.
  • Full Queue: If the queue reaches its capacity, the system temporarily stops accepting new tasks until space becomes available.

Best Practices to Avoid Queue Issues:

  • Submit tasks at a steady rate rather than in large batches.
  • Pay attention to headers indicating queue status or wait times.
  • Implement robust error handling and automatic retries for 503 errors.


  • No labels