Learn how to use the Domino API and the different methods you can use securely authenticate into Domino programmatically.
To interact with secured endpoints of the Model Monitoring API or Domino REST 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.
To authenticate your requests, include your API key with the header X-Domino-Api-Key.
-
Go to Account Settings.
-
Go to Settings > API Key to see your key.
|
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. |
|
Note
|
This JWT token functionality is disabled by default in Domino 5.5+. 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
| Model APIs do not provide JWT tokens in their environment. |
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.
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.
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.
-
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"} -
The API proxy runs and
$DOMINO_API_PROXYcontains the proxy address.
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).
However, it is recommended to migrate workflows to use the JWT proxy for API access instead, as the JWT proxy is more reliable.
See Use a Token for Authentication for more information about JWT propagation.
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.
-
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"} -
The API proxy runs and
$DOMINO_API_PROXYcontains the proxy address.
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).
However it is recommended to migrate workflows to use the JWT proxy for API access instead, as the JWT proxy is more reliable.
See Use a Token for Authentication for more information about JWT propagation.