Domino Service Accounts (DSAs) provide a secure way to access the Domino API without relying on personal user credentials. They are automation principals: technical users managed by administrators, not human users behind a browser. DSAs can’t log in through the Domino web interface or CLI, and they are the only accounts permitted to use long-lived API tokens.
Each DSA can have one or more tokens, each with its own independent lifespan. By default, tokens expire after four months. Tokens inherit the DSA’s roles at creation and can be revoked individually or by deactivating the DSA. This allows administrators to control access precisely while maintaining security. Typical use cases include: CI/CD pipelines, external monitoring or automation tools, and system-to-system integrations.
DSAs simplify automation by providing a stable identity with scoped permissions, independent of personal user accounts.
The DSA lifecycle includes:
-
Creating the account.
-
Assigning or adjusting roles.
-
Generating a token (which inherits roles at creation).
-
Using a token to authenticate.
-
Reviewing tokens regularly to rotate or revoke them as needed.
A Domino Service Account (DSA) is created through the Domino API. Only Administrators can create service accounts.
When you create a DSA, it inherits the roles of the user who created it. You can later assign or remove roles directly on the DSA. Tokens generated for the DSA will reflect the roles present at the time of token creation.
|
Note
|
The easiest way for an administrator to communicate with Domino via API is from inside a Workspace (for example, Jupyter). Open a Terminal in the Workspace and use the API Proxy, which automatically authenticates calls to Domino APIs. The examples in this guide assume that they are executed from inside a Workspace using the API Proxy. To make API calls from outside of Domino, follow the authentication instructions in the Domino API documentation. |
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.
Example request:
POST /v4/serviceaccounts
{
"userName": "demo-sa",
"email": "demo-sa@customer.com"
}Example response:
{
"id": "abcd1234",
"userName": "demo-sa",
"email": "demo-sa@customer.com",
"idpld": "ca72dc97-504b-4b3c-98d6-3a306b30bd24"
}Roles define what a Domino Service Account (DSA) can do. When you create a DSA, it inherits the roles of the user who created it. You can add or remove roles later to match the needs of the automation or integration. You can manage roles using the Admin panel in Domino.
Key points
-
Roles control the scope of access for any tokens generated from the DSA.
-
Tokens capture the DSA’s roles at the time of creation. If you later change roles, generate a new token to reflect the updated permissions.
-
Common roles include:
-
Practitioner- Uses compute and file storage -
SupportStaff- Manages compute-related functionality
-
After you create a Domino Service Account (DSA), generate a token so it can authenticate in API requests or automation workflows.
Token name field
The name field in the token creation request is an arbitrary label. It does not need to match the DSA’s userName or email. Use a descriptive value that indicates the purpose of the token.
The serviceAccountIdpId uniquely identifies the DSA and is required in API calls. You can save the value in the IDPID environment variable for future use.
Example request:
POST /v4/serviceAccounts/$IDPID/tokens
{
"name": "token-for-circleci"
}Example response:
{
"createdAt" : "2024-02-15T00:39:35.521Z",
"expiresAt" : "2024-06-14T00:39:35.513201660Z",
"isValid" : true,
"name" : "token-for-circleci",
"serviceAccountIdpId" : <IDPID>,
"token" : "eyJhbGciOiJSUzI1N..."
}Key points
-
The token is active immediately after creation.
-
The name is for identification only. It does not affect permissions.
-
The serviceAccountIdpId uniquely identifies the DSA and is required in API calls.
-
Save the value of the idpId property in the IDPID environment variable for future use.
-
Store tokens securely. You will need to pass it as a bearer token in API requests or configure it in automation systems that act on behalf of the DSA.
Tokens authenticate automation systems or external tools on behalf of a Domino Service Account (DSA). Use them in place of personal credentials.
Tokens act as credentials for a Domino Service Account (DSA). DSA tokens expire by default four months after creation. If a token expires, a new one will need to be created.
You can also rotate or revoke tokens regularly to maintain security and to align with changes in role assignments.
List tokens for a DSA
Use the Domino API to return all tokens associated with a DSA. This is useful for auditing or identifying tokens to revoke.
Example request:
GET /v4/serviceAccounts/$IDPID/tokensExample response:
[
{
"id": "efgh5678",
"name": "token-for-circleci",
"createdAt": "2024-02-15T00:39:35.521Z",
"expiresAt": "2024-06-14T00:39:35.513201660Z",
"isValid": true
},
{
"id": "ijkl9012",
"name": "token-for-monitoring",
"createdAt": "2024-03-01T10:22:11.100Z",
"expiresAt": "2024-07-01T10:22:11.100Z",
"isValid": false
}
]When creating multiple DSAs, you can use plus addressing to distinguish them while reusing the same base email address. For example:
automation+ci@customer.com
automation+monitoring@customer.com
automation+etl@customer.comDomino treats each address as a unique identity, even though they all route to the same base mailbox - automation@customer.com. This approach simplifies administration while keeping service accounts separate in Domino.