Service accounts

A service account is a special type of account, distinct from a user account, which you can use to authenticate and interact with SpatialOS. You can create and manage service accounts using the Platform SDK.

Service accounts consist of several components:

  • a descriptive name outlining what the service account is used for
  • a cloud project name which is the name of the project associated with the service account - anyone who is part of the project is able to view basic details about the service account
  • an expiry time at which point the service account will become invalid
  • a list of permissions which specify what the service account can do
  • a refresh token which you provide as authentication to services
  • an ID used to update and delete the service account

When running automated jobs such as performing game maintenance, you should use a refresh token belonging to a service account instead of your personal refresh token.

Using service accounts

As a rule of thumb, if you are performing an action yourself, you should use your own refresh token for authentication. If you are providing a refresh token as a parameter or variable in a script or automated task, create a service account with the required permissions and use that refresh token instead.

  • 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.
  • Permissions

    Permissions are tied to a service account and determine what it can read, write, and grant others access to.

    A single permission comprises two components: verbs and path.

    A service account can have an unlimited number of permissions. However, you should give a service account as few permissions as possible for security reasons. Give a service account only the permissions it needs to perform its actions.


    Verbs are how you specify what a service account can access for a given permission. There are three verbs.

    Verb What it means
    Read Read (including listing) from a resource
    Write Write (including creating and deleting) to a resource
    Grant Grant permissions for a resource to service accounts

    Think carefully about which verbs you assign to a permission. For security reasons, you can't give Grant permissions to a service account. Only users can possess a Grant permission.


    The path is a list of strings known as parts which specify the services or projects the service account has access to.

    Path What it means
    prj, my_project, * Access the project with name my_project
    srv, * Access metrics services

    More paths will become available in later versions.

    Now that you have seen both verbs and paths, you can construct a permission. For example, you might want to use the deployment service to manage to the deployments for your game in the project called my_project. In this case, you need read and write access to the path with parts prj, and my_project, and read access to the path with the part srv. These are represented as:

    var permProject = new Permission
        Parts = {new RepeatedField<string> {"prj", "my_project", "*"}},
        Verbs =
            new RepeatedField<Permission.Types.Verb>
    var permServices = new Permission
        Parts = {new RepeatedField<string> {"srv", "*"}},
        Verbs =
            new RepeatedField<Permission.Types.Verb>


    When you create a service account, you should also provide a reasonable Lifetime which is a duration determining when the service account will expire and become invalid.

    If a service account is used after it has expired, the refresh token will be invalid and will not function as expected.

    Although a lifetime is not mandatory, we recommend including an explicit Lifetime for security reasons. To automatically increase service account expiry times before they expire, see Service account maintenance.

    Updated about a year ago

    Service accounts

    Suggested Edits are limited on API Reference Pages

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