Service accounts#

Service accounts in Neptune workspace settings

Service accounts are a special type of non-human privileged account. You can use them for automated processes instead of maintaining user accounts for this purpose.

Service accounts are workspace-specific. They can log data to Neptune projects they've been assigned to and perform management actions on users and projects (except deleting them).

Why should I use a service account?#

Service accounts are helpful:

For automating your workflow
If you need a non-user API token
If you need to use multiple API tokens

Service accounts are also good for scoping permissions. They can have lower permission levels and access only to necessary projects.

What's different about service accounts?

Workspace admins can instantly revoke a service account's API token in the workspace settings, which helps improve the security of your setup.
A service account cannot access any projects automatically. To perform actions in a project, it has to be explicitly assigned to it with at least "contributor" permissions.
Service accounts can't delete projects or have the workspace admin role. As such, service accounts cannot use the following functions from the management API:
- delete_project()
- invite_to_workspace()
Otherwise, service accounts can perform project actions according to their permissions.
You can have up to 50 service accounts per workspace.

What to use service accounts for

Your shared training/evaluation pipeline
CI/CD servers that do something like validating models marked for staging
Monitoring services that regularly check how models behave
Report generation

Creating a service account#

To create a new service account in your workspace:

In the top-left corner of the Neptune app, click your workspace name → Service accounts → New service account.
Enter a name for the service account.

The full name of the account will be <service-account-name>@<workspace-name>.
To grant contributor access to all projects in the workspace, check the corresponding box.

Otherwise, you'll need to manually assign the service account to each project it should have access to. Setting the project privacy to "workspace" does not make it accessible to service accounts.

Once done, workspace admins can manage and access the API token of the service account.

Assigning a service account to a project#

Before adding a service account to a project, you need to create it in the workspace settings.

When creating the account, you can choose to grant it access to all projects that exist at the time. If you did not grant universal access, or you create a new project after that, you need to assign the service account to the project manually.

You can grant access:

Via the web app, by going to the project settings menu ( ) in the top-right and selecting Service accounts.

Via the API, with the management.add_project_service_account() function.

Add service account to project

>>> from neptune import management
>>> management.add_project_service_account(
...     project="ml-team/classification",
...     service_account_name="cicd@ml-team",
...     role="contributor",
... )

Note

A service account cannot access projects with "workspace" visibility. It must be explicitly assigned to a project to be able to access it.

Managing service accounts#

Workspace admins and project owners can do the following:

Access service account settings.
Add a service account to a project (needs to be created in the workspace settings first).
Remove a service account from a project.
Change the service account role within a project.

Only workspace admins can access and manage the Neptune API tokens of service accounts. If a service account is deactivated and then reactivated, the API token is refreshed.

Tip

You can also managage service accounts through the management API.

Most of the management operations can themselves be performed by service accounts.

Deactivating a service account#

To revoke the access of a service account:

As workspace admin, navigate to the workspace settings: In the top-left corner of the Neptune app, click your workspace name → Service accounts.
On the account you want to deactivate, open the menu and select Deactivate.

Deactivating a service account makes its API token unusable.

You can reactivate the account later, but you'll have to update the API token in your code.

Reactivating a service account#

To restore a service account:

As workspace admin, navigate to the workspace settings: In the top-left corner of the Neptune app, click your workspace name → Service accounts.
On the account you want to deactivate, click Reactivate.
Update the API token where the service account was used.

This is needed because deactivation resets the API token.