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. |
To authenticate your requests, include your API key with the header X-DMM-API-KEY.
Use the API Token page to generate a user-specific authentication token that is used when making requests to the Model Monitor’s public APIs.
-
From the navigation pane, click Model Monitor.
-
Click Settings.
-
Click API Token.
-
Click the Copy Token icon and replace the auth token parameter in the Model Monitoring REST API calls.
|
Note
|
After a token has been generated, you can click Revoke Token if necessary, based on your security policy. |
|
Note
| See Use the API Proxy for Domino API Authentication for the newest information. |
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. |
Workspaces, Jobs, Apps, Scheduled Jobs, and Launchers have a Domino Token for the user.
This is at path /var/lib/domino/home/.api/token.
This is indicated by environment variable DOMINO_TOKEN_FILE.
By default, the Domino Token expires at five minutes, but is automatically refreshed throughout your Workspace or Job.
For example, from a Workspace, you can authenticate to one of the Domino APIs with the following:
TOKEN=`cat $DOMINO_TOKEN_FILE`
curl -H "Authorization: Bearer $TOKEN" $DOMINO_API_HOST/v4/users/selfEach 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.
|
Note
| To minimize the impact to upgrades from releases prior to Domino 5.4, Domino is retaining access to JWT propagation. |
-
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.
This is the default in existing deployments.
-
The
EnableLegacyJwtToolingfeature flag is set totrueby default. -
The token refresher runs periodically.
$ curl "$DOMINO_API_HOST/v4/users/self" -H "Authorization: Bearer $(cat $DOMINO_TOKEN_FILE)" //{"firstName":"Jack","lastName":"London","fullName":"Jack London","userName":"jack-london","email":"jack.london@oaklandpub.com","avatarUrl":"","id":"123456789"}
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.
|
Note
| To minimize the impact to upgrades from releases prior to Domino 5.4, Domino is retaining access to JWT propagation. |
-
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.
This is the default in existing deployments.
-
The
EnableLegacyJwtToolingfeature flag is set totrueby default. -
The token refresher runs periodically.
$ curl "$DOMINO_API_HOST/v4/users/self" -H "Authorization: Bearer $(cat $DOMINO_TOKEN_FILE)" //{"firstName":"Jack","lastName":"London","fullName":"Jack London","userName":"jack-london","email":"jack.london@oaklandpub.com","avatarUrl":"","id":"123456789"}See Use a Token for Authentication for more information.