Setup and installation

Setup and installation: Platform SDK (in C#)


The SDK is compiled against .NET Framework 4.5.1 and .NET Standard 1.5, so it should work on any compatible .NET framework version. Both Mono 5 or .NET Core 2 are good choices that work on Linux, MacOS and Windows.

Downloading the C# Platform SDK

You can download the Platform SDK in C# using NuGet (unless you're using a secure environment).



  • In a terminal window, run nuget install Improbable.SpatialOS.Platform -OutputDirectory packages, which installs it into the directory “packages” relative to current directory.

Secure environments

For secure environments, the SpatialOS CLI package manager is the only option for downloading a bundle of the DLL and XML and its dependencies together.

To download to the file, run:

spatial package get platform_sdk csharp <version>

Once downloaded, unzip the file and reference all DLLs. The dependencies include the C# gRPC runtime, which you can't reference directly, but you should still include it in your project and configure it to be copied to the output folder.

Authenticating your API calls

We require authentication to use the Platform SDK. It uses the same SpatialOS refresh token attached to a normal account or service account to authenticate your API calls. As a result, you must have either a SpatialOS user account or a service account to use the SDK.

On the command-line

The SDK is built to work together with the SpatialOS CLI's built-in authentication mechanism. Alternatively, you can provide a refresh token string for the Platform SDK to use directly.

To use the SpatialOS CLI's built-in authentication mechanism, run spatial auth login. This obtains a copy of your refresh token and caches it locally. By default, the Platform SDK looks for the refresh token file stored locally (see the spatial auth login documentation for details) and uses it to authenticate. Refresh tokens for normal user accounts expire relatively quickly; we're currently working on a service account API which will let you set a longer expiry time.

  • Create a separate service account for each individual script or task you need to perform, to avoid exposing unnecessary permissions to parts of your code and causing a security risk. A more granular service account structure also allows you to revoke one of your services access by deleting the service account without affecting your other services.
  • Make sure any machines are secure by using encrypted disks.
  • Never output the refresh token in a log message.
  • Never commit the refresh token to a repository.
  • Self-hosted service

    If the code that is calling the Platform SDK resides in a service that you are hosting then you should make use of a service account for authentication. This could for example be the logic managing the set of deployments hosting your game and to which players can connect.

    Service accounts can be created and managed via the Service Account Service.

    Server worker

    In the case where a server worker needs to be making calls to the Platform SDK, for example in order to set a tag on the deployment in which it is running, the deployment environment can provide ready-to-go authentication. The provided token has permissions limited to the deployment itself to prevent a server worker from one deployment accidentally interferring with another of your deployments. In order to use it:

    1. In your server worker's launch configuration use the ${IMPROBABLE_PLATFORM_REFRESH_TOKEN} placeholder to pass a token to the worker.
    2. Use the token value within the worker to set the identically named IMPROBABLE_PLATFORM_REFRESH_TOKEN environment variable. For example with:
       static int Main(string[] args)
           // ...
           Environment.SetEnvironmentVariable("IMPROBABLE_PLATFORM_REFRESH_TOKEN", args[4])
           // ...
           var deploymentClient = DeploymentServiceClient.Create();
    1. The Create method of the various service clients provided by the SDK will read the environment variable and use it to set up the authentication of any subsequent API calls.

    Updated about a year ago

    Setup and installation

    Suggested Edits are limited on API Reference Pages

    You can only suggest edits to Markdown body content, but not to the API spec.