Get SpatialOS



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.

Service accounts consist of several components:

  • a descriptive name outlining what the service account is used for
  • a 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.

You can create and manage service accounts using the Platform SDK.

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. If you create a ‘master’ service account for all of your scripts, you risk exposing unnecessary permissions to parts of your code and causing a security risk. Additionally, a more granular service account structure allows you to revoke one of your services access by deleting the service account without affecting your other services.


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. Using the Platform SDK, this is represented as:

var perm = new Permission
    Parts = {new RepeatedField<string> {"prj", "my_project"}},
    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.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums