Manage Domino Service Accounts

Domino Service Accounts provide a managed and secure way to access the Domino API from outside of the Domino cluster. Domino Service Accounts provide stable, token-based authentication for API calls without compromising the accounts of individual Domino users and the assets they have access to. Service Accounts are especially useful when calling the Domino API as part of an automation pipeline.

What are Domino Service Accounts?

Domino Service Accounts are a special type of Domino user. They don’t represent a human being behind a browser, but rather a "technical user", "service account", or "automation principal" — all these terms describe a digital identity used by software programs to communicate with other software.

Each Service Account can have one or more long-lived tokens associated with it which are used to authenticate calls to the Domino API. Each token has its own independent lifespan but points to the same Service Account, for which it was created. Each token created for the same Service Account gives the token bearer access to the same Projects.
Only Service Accounts can have long-lived credentials for calling Domino APIs. Regular Domino users are not allowed to have long-lived tokens.
Service Accounts are not allowed to utilize the web interface, Domino, or Domino CLI.
Service Accounts are managed by Domino Administrators and are not accessible to regular Domino users. Admins create and archive the Service Accounts, as well as generate and manage their tokens. If compromised, each token can be invalidated individually, or the whole service account can be deactivated, effectively prohibiting any access using its tokens.
Service Accounts can be invited to collaborate on a Project, just like a regular user. This gives the Service Account access to code and data in that particular Project.

Create a Service Account

Domino Service Accounts can only be managed with the Domino APIs. The calling user must have an Administrator role.

Note

The easiest way for an Administrator to communicate with Domino via API is to start a Workspace (e.g. Jupyter) in Domino, start a Terminal inside the Workspace, and take advantage of the API Proxy, which will automatically authenticate the calls to Domino APIs.

The following examples assume that they are executed from inside a Workspace and use the API Proxy. To make these calls from outside of Domino, authenticate as described by the documentation for Domino API.

To create a Service Account, the Administrator makes a call to the /v4/serviceAccounts endpoint, supplying the desired username for the Service Account and a valid email address. Domino Service Accounts, just like regular Domino users, need a valid and unique email address. Domino uses this email address to send notifications, inform about failed jobs, and for other purposes.

$ curl -X POST -H 'Content-Type: application/json' \
  -d '{"username": "demo-sa", "email": "demo-sa@customer.com"}' \
  $DOMINO_API_PROXY/v4/serviceAccounts

Result:

{
    "email": "demo-sa@customer.com",
    "id": "65cd5ca022e1a963208d7a6d",
    "idpId": "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
    "userName": "demo-sa"
}

Save the value of the "idpId" property in the IDPID environment variable for future use.

Create multiple Service Accounts emails with "plus addressing"

To manage multiple unique email addresses, you can use "plus addressing" or "subaddressing" to create multiple email addresses for your Service Accounts without requiring you to create new email accounts.

Many email services, like Gmail, Google Workspace, Microsoft Exchange Online, and others support "plus addressing" (or "subaddressing") — an industry-defined way to support dynamic recipient email addresses.

For example, if you have an email like riley@gmail.com, you can create a Service Account for an Apache Airflow pipeline with the email address riley+airflow@gmail.com. Domino will send all activity related to the Apache Airflow Service Account to the riley@gmail.com inbox tagged with the tag airflow. This way, a single user can manage multiple service accounts from one inbox.

Check with your enterprise email provider to see if subaddressing is supported at your company.

List Service Accounts

Admins can list all the existing Service Accounts in Domino.

$ curl $DOMINO_API_PROXY/v4/serviceAccounts

Result:

[
   {
      "email" : "demo-sa@customer.com",
      "id" : "65cd5ca022e1a963208d7a6d",
      "idpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
      "username" : "demo-sa"
   }
]

Create a token

Admins can create a token for a Service Account using the Service Accounts idpId.

Each token has a default lifespan of 4 months, which is listed in the response above.

The value of the token property can be copied and used to authenticate the calls to Domino APIs. The caller will be recognized as the Service Account to which this token belongs. Let’s save the value to the SA_TOKEN environment variable for the next example.

In this example, IDPID is an environment variable that contains the idpId of the Service Account.

$ curl -X POST -H 'Content-Type: application/json' \
  -d '{"name": "token-for-circleci"}' \
  $DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens

Result:

{
   "createdAt" : "2024-02-15T00:39:35.521Z",
   "expiresAt" : "2024-06-14T00:39:35.513201660Z",
   "isValid" : true,
   "name" : "token-for-circleci",
   "serviceAccountIdpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24",
   "token" : "eyJhbGciOiJSUzI1N... redacted for brevity ...kNY_DlWXl8WJPvjTJsPeddd40u9dUhDp-FDg"
}

Start a Job with a Service Account

The following example starts a Domino Job using the token value from the previous "Create a token" step.

$ curl -H "Authorization: Bearer $SA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "projectId": "12398gg098", "runCommand": "main.py"}' \
  $DOMINO_API_HOST/api/jobs/v1/jobs

Note	This call goes to $DOMINO_API_HOST, which does not automatically add authentication.

List all tokens

List all existing tokens for a Service Account. The "List tokens" response contains the expiration dates of all the tokens. Monitoring this and taking proactive steps helps avoid service interruptions when using the tokens.

$ curl -s $DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens

Result:

[
   {
      "createdAt" : "2024-02-15T00:39:35.521Z",
      "expiresAt" : "2024-06-14T00:39:35.513Z",
      "isValid" : true,
      "name" : "token-for-circleci",
      "serviceAccountIdpId" : "ca72dc97-504b-4b3c-98d6-3a306b30bd24"
   }
]

Invalidate a token

If a token is compromised or is no longer needed, it can be invalidated. This won’t affect other tokens belonging to this or any other Service Account.

$ curl -H 'Accept: application/json' -X POST \
  $DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/tokens/token-for-circleci/invalidate

Deactivate a Service Account

If the whole Service Account is no longer necessary, it can be deactivated, making all its tokens invalid.

$ curl -X POST -H 'Content-Type: application/json' \
  $DOMINO_API_PROXY/v4/serviceAccounts/$IDPID/deactivate

Service Accounts best practices

To lower the risk of exposing sensitive Project data and code, Domino recommends minimizing the number of Projects on which a single Service Account collaborates.
To help the Administrators map Service Accounts to Projects, the username can be crafted to reflect the relationship between the Service Account and the Project.
Domino recommends that you use one token for a single purpose (for example, in a single automation pipeline). It’s helpful if the token name reflects where it’s being used. This way, if a token needs to be replaced, it could be done without affecting many scripts or automation pipelines.
The "List tokens" API response contains the expiration dates of all the tokens. Monitoring this and taking proactive steps helps avoid service interruptions when using the tokens.

Next steps

Explore the Domino REST API reference.

See other methods users can authenticate against the Domino API.