How do I create an authentication journey via REST in Identity Cloud?

Overview

When creating authentication journeys using the REST API, you should be aware of the following key points:

• You must re-create each node in order to create a new authentication journey.
• Each node must have a valid UUID as its identifier; you can generate UUIDs online, for example: Online UUID Generator. If you don't use a valid UUID, authentication will fail.
• The Success/Failure nodes have static UUIDs that remain constant across all authentication journeys. These UUIDs are as follows:
  • Success node: 70e691a5-1e33-4ac3-a356-e7b6d60d92e0
  • Failure node: e301438c-0bd0-429c-ab0c-66126501069a
• The identityResource property specified when creating the authentication journey is the identities that will authenticate using the journey, for example, managed/alpha_user.
• The entryNodeId property specified when creating the authentication journey is the UUID of the first node in the journey.
• The outcome property specified when creating the authentication journey is the UUID of the next node; this is how you move between the nodes.
• If you examine a journey, you will notice x and y properties, which determine the positions of each node within the journey when viewed in the Identity Cloud admin UI. These properties are optional as they only affect the layout; if you do want to view the resulting journey in the Identity Cloud admin UI, you can click the Auto Layout button to automatically reposition the nodes to make them all visible.

Prerequisites

Before you can make any of the REST calls detailed in this article, you will need an access token. See Authenticate to Identity Cloud REST API with access token for further information.

Examining an existing journey

You can use a GET call to examine an existing journey. For example:$ curl --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/<journey-name>' \ --header 'authorization: Bearer <access-token>'Where <tenant-env-fqdn> is your Identity Cloud tenant name, <journey-name> is the name of the journey you want to examine and <access-token> is the access token you obtained when you authenticated to the Identity Cloud REST API.

The response will help you understand the format, and also provide the node type names and _ids that should be used for creating the nodes; noting that the UUID (_id) must always be unique for each node.

Alternatively, you can export journeys to view the associated details. See Export journeys for further information.

Creating a journey using the REST API

The following example demonstrates creating a simple authentication journey that consists of three nodes (ValidatedUsernameNode, ValidatedPasswordNode and DataStoreDecisionNode) using the REST API. 

1. Generate UUIDs for each of the nodes you want to create. For example:
   • ValidatedUsernameNode: 8f9d2280-caa7-433f-93a9-1f64f4cae60a
   • ValidatedPasswordNode: 54f14341-d1b7-436f-b159-d1f9b6c626eb
   • DataStoreDecisionNode: 3fc7ce22-fc79-4131-85f2-f1844709d042
2. Create the ValidatedUsernameNode node using the following curl command, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API and the UUID with the one you generated: $ curl --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/ValidatedUsernameNode/8f9d2280-caa7-433f-93a9-1f64f4cae60a' \ --header 'authorization: Bearer <access-token>' \ --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'If-None-Match: *' \ --data-raw '{   "_id":"8f9d2280-caa7-433f-93a9-1f64f4cae60a",    "_type":        {"_id":"ValidatedUsernameNode",         "name":"Platform Username"        }    }'Example response: {"_id":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","_rev":"-1253594328","usernameAttribute":"userName","validateInput":false,"_type":{"_id":"ValidatedUsernameNode","name":"Platform Username","collection":true},"_outcomes":[{"id":"outcome","displayName":"Outcome"}]}
3. Create the ValidatedPasswordNode node using the following curl command, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API and the UUID with the one you generated: $ curl --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/ValidatedPasswordNode/54f14341-d1b7-436f-b159-d1f9b6c626eb' \ --header 'authorization: Bearer <access-token>' \ --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'If-None-Match: *' \ --data-raw '{   "_id":"54f14341-d1b7-436f-b159-d1f9b6c626eb",    "_type":        {"_id":"ValidatedPasswordNode",         "name":"Platform Password"        }    }'Example response: {"_id":"54f14341-d1b7-436f-b159-d1f9b6c626eb","_rev":"1828577410","validateInput":false,"passwordAttribute":"password","_type":{"_id":"ValidatedPasswordNode","name":"Platform Password","collection":true},"_outcomes":[{"id":"outcome","displayName":"Outcome"}]}
4. Create the DataStoreDecision node using the following curl command, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API and the UUID with the one you generated: $ curl --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/DataStoreDecisionNode/3fc7ce22-fc79-4131-85f2-f1844709d042' \ --header 'authorization: Bearer <access-token>' \ --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'If-None-Match: *' \ --data-raw '{   "_id":"3fc7ce22-fc79-4131-85f2-f1844709d042",    "_type":        {"_id":"DataStoreDecisionNode",         "name":"Data Store Decision"        }    }'Example response: {"_id":"3fc7ce22-fc79-4131-85f2-f1844709d042","_rev":"2145625368","_type":{"_id":"DataStoreDecisionNode","name":"Data Store Decision","collection":true},"_outcomes":[{"id":"true","displayName":"True"},{"id":"false","displayName":"False"}]}
5. Create the authentication journey with these three nodes, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API and the UUIDs with the ones you used to create the nodes. 

Ensure you specify the identityResource property, set entryNodeId to the UUID of the first node and set the outcome of each node to the UUID of the next node. For example: $ curl --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/mySampleAuthJourney' \ --header 'authorization: Bearer <access-token>' \ --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --header 'If-None-Match: *' \ --data-raw '{   "identityResource":"managed/alpha_user",    "entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a",    "nodes":{      "8f9d2280-caa7-433f-93a9-1f64f4cae60a":{        "displayName":"Platform Username",        "nodeType":"ValidatedUsernameNode",        "connections":{          "outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"          }        },       "54f14341-d1b7-436f-b159-d1f9b6c626eb":{         "displayName":"Platform Password",         "nodeType":"ValidatedPasswordNode",         "connections":{           "outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"           }         },       "3fc7ce22-fc79-4131-85f2-f1844709d042":{         "displayName":"Data Store Decision",         "nodeType":"DataStoreDecisionNode",         "connections":{           "false":"e301438c-0bd0-429c-ab0c-66126501069a",           "true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"}         }       }   }'Example response: {"_id":"mySampleAuthJourney","_rev":"-773762003","identityResource":"managed/alpha_user","uiConfig":{},"entryNodeId":"8f9d2280-caa7-433f-93a9-1f64f4cae60a","nodes":{"8f9d2280-caa7-433f-93a9-1f64f4cae60a":{"displayName":"Platform Username","nodeType":"ValidatedUsernameNode","connections":{"outcome":"54f14341-d1b7-436f-b159-d1f9b6c626eb"}},"54f14341-d1b7-436f-b159-d1f9b6c626eb":{"displayName":"Platform Password","nodeType":"ValidatedPasswordNode","connections":{"outcome":"3fc7ce22-fc79-4131-85f2-f1844709d042"}},"3fc7ce22-fc79-4131-85f2-f1844709d042":{"displayName":"Data Store Decision","nodeType":"DataStoreDecisionNode","connections":{"false":"e301438c-0bd0-429c-ab0c-66126501069a","true":"70e691a5-1e33-4ac3-a356-e7b6d60d92e0"}}},"enabled":true}

The resulting journey created from this example looks like this (with the nodes repositioned so they are all visible):

See Also

Journeys in Identity Cloud

Journeys

Authentication nodes and journeys