Domino API authentication

Learn how to use the Domino API and the different methods you can use securely authenticate into Domino programmatically.

Authenticate with a Service Account token

Domino provides a convenient way for external software and automation pipelines to access Domino APIs via Domino Service Accounts. These accounts are managed by the Domino Administrators and have long-lasting credentials, making them easy to use in other parts of the enterprise outside of Domino.

See Domino Service Accounts documentation for more information.

Once you receive your token from an admin, you can use the token to authenticate and run Domino API calls.

The following example starts a Domino Job using the SA_TOKEN. As an additional security measure, you should store the SA token as a custom environment variable for secure credential storage.

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

Authenticate with an API key

To interact with secured endpoints of the Model Monitoring API or Domino Platform API, you must send an API authentication token or key along with your request. This parameter identifies you as a specific Domino user so Domino can check for authorization.

Find your Domino Rest API key

Caution
 This feature will be deprecated in future versions of Domino. Domino recommends using Service Accounts as they provide stable, token-based authentication for API calls, independent access management, and stronger security.

To authenticate your requests, include your API key with the header X-Domino-Api-Key.

Get your API key

  1. Go to Account > Account Settings > API Key.

  2. Click Regenerate to produce a API key. You will only be able to view this once.

Caution
 Anyone with this key can authenticate to the Domino application as the user it represents and take any actions that user is authorized to perform. Treat it like a sensitive password.

Authenticate with a JWT Token

Caution
 This JWT token functionality is disabled by default in Domino 5.5+ and will be deprecated in upcoming Domino versions. Instead, you should use the API Proxy for Domino API authentication. The JWT token functionality described on this page is only present for backwards-compatibility; to use it, you must enable the EnableLegacyJwtTooling feature flag.

Domino uses the OpenID Connect (OIDC) protocol to generate user-specific JWT tokens, or Domino Tokens. Domino securely signs this Domino token and makes it available in your Workspace, Job, App, Scheduled Job, or Launcher. You can use it to authenticate to third-party resources or data sources. Additionally, this token can be used to authenticate with the Domino API.

Because the token is short-lived and Domino automatically refreshes it, an example of when you can use it is if you want to limit a user’s access to a data source exclusively from Domino. This has security advantages over provisioning long-lived keys that can be used anywhere or by anyone.

Note
 Domino endpoints do not provide JWT tokens in their environment.

Configure a service to trust Domino’s JWT

Each system will have different steps for configuration but will likely require that you enter Domino’s JWKS endpoint which is <Domino URL>/auth/realms/DominoRealm/protocol/openid-connect/certs>. For offline services, retrieve and record the JWKS data to use offline with your library. Alternatively, you can use the public key or certificate which can be found at <Domino URL>/auth/realms/DominoRealm.

See JSON Web Key Sets to learn more about JWKS.

Token claims

By default, the Domino Token contains standard claims like name, username, and email, but you add mappers in the domino-play client in Keycloak to include additional custom claims. This can be useful if you intend to set up bounded claims in the system to which you are integrating. For example, you might want to only authorize users with a specific organization claim or any other SAML assertion that flows into Domino from your Identity Provider.

Use the API Proxy for Domino API Authentication

You can use the API proxy to authenticate calls to Domino APIs using the address and port exposed by the proxy process. If you make a call to Domino and use this proxy, the proxy automatically adds the authentication information (the access JWT token) to the proxied request.

Authentication with the API proxy

  1. The run starts immediately and the token is acquired when the first call is made through the proxy:

    $ curl "$DOMINO_API_PROXY/v4/users/self"
{"firstName":"Jack","lastName":"London","fullName":"Jack London","userName":"jack-london","email":"jack.london@oaklandpub.com","avatarUrl":"","id":"123456789"}

  2. The API proxy runs and $DOMINO_API_PROXY contains the proxy address.

Authentication with JWT propagation

Prior to Domino 5.4, authentication was done using JWT propagation, where Domino injected a file into Jobs and Workspaces containing access credentials. This has been deprecated, but if user workflows have not yet been migrated, the EnableLegacyJwtTooling feature flag is available. It is set to false by default, but can be set to true to enable legacy JWT propagation behavior (while also retaining the proxy behavior).

It is recommended to migrate workflows to use the JWT proxy for API access instead, as the JWT proxy is more reliable and the legacy behavior will be deprecated and removed in future Domino versions.

See Use a Token for Authentication for more information about JWT propagation.

Additional resources

See JWT.io for information about decoding and inspecting the content of a JWT token.

You can use the API proxy to authenticate calls to Domino APIs using the address and port exposed by the proxy process. If you make a call to Domino and use this proxy, the proxy automatically adds the authentication information (the access JWT token) to the proxied request.

Authentication with the API proxy

  1. The run starts immediately and the token is acquired when the first call is made through the proxy:

    $ curl "$DOMINO_API_PROXY/v4/users/self"
{"firstName":"Jack","lastName":"London","fullName":"Jack London","userName":"jack-london","email":"jack.london@oaklandpub.com","avatarUrl":"","id":"123456789"}

  2. The API proxy runs and $DOMINO_API_PROXY contains the proxy address.

Authentication with JWT propagation

Prior to Domino 5.4, authentication was done using JWT propagation, where Domino injected a file into Jobs and Workspaces containing access credentials. This has been deprecated, but if user workflows have not yet been migrated, the EnableLegacyJwtTooling feature flag is available. It is set to false by default, but can be set to true to enable legacy JWT propagation behavior (while also retaining the proxy behavior).

It is recommended to migrate workflows to use the JWT proxy for API access instead, as the JWT proxy is more reliable and the legacy behavior will be deprecated and removed in future Domino versions.

See Use a Token for Authentication for more information about JWT propagation.