Sending customer-based user notifications

This article explains how to send notifications to Cloud Identity Plane (CIP) users while taking the customer context into account.

About this tutorial

CIP provides APIs allowing you to send e-mail notifications to users in two ways:

  • Send notifications to users within the current customer context (user notification API).

  • Send notifications to all users across multiple customers (customer notification API).

Following this tutorial, you can try out the customer notification API. You’re going to perform the following actions:

  1. Authenticate to CIP to get an SSO token.

  2. Send a customer-based notification request to CIP using the received token.


  • CIP up and running

  • Administrator account in CIP with the ADMIN_SEND_CUSTOMERS_NOTIFICATION_MESSAGE entitlement

Send notifications to customers

  1. Authenticate to CIP as an administrator by sending a request to

    • Replace with your actual CIP domain.

    • Set identifier and password to your own credentials.

    curl --verbose POST '' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "identifier": "YOUR_IDENTIFIER",
    "password": "t0ps3cr3t"


    Authorization token is returned in the response body (code 201 is returned). Save this token.

    < HTTP/2 201
    < date: Tue, 08 Jun 2021 12:41:01 GMT
    < content-type: application/json
    < content-length: 48
    < server: nginx
    < trace-id: 23b5a553fb95a19c
    < access-control-allow-credentials: true
    < access-control-allow-headers: *
    < access-control-allow-methods: *
    < access-control-max-age: 600
    * Connection #0 to host left intact
    {"token":"0d25bdba-009b-47a9-a985-554692572b1e"}* Closing connection 0

    More information

    You can read more about authentication options in the REST API authentication documentation.

  2. Send a notification request to the endpoint. Provide the following data in the body:

    • target (required) - which users should receive the e-mail. Can be ALL_USERS (all users in all organizations) or SELECTED_CUSTOMER_USERS (users belonging to specific organizations only).

    • identifiers - complementary information to target. Specifies which users should receive the e-mail based on their parent organization. If target is set to ALL_USERS, this information is redundant (notifications are sent regardless of the organization). Use customer IDs (cid) as identifiers.

    • emailParams (required) - defines which template to use and what the e-mail subject is. templateId must point to a template available in your CIP deployment (for details, see Configuring notification templates).

    • emailContent - data related to the contents of the e-mail.

    All parameters and their options are explained in the API documentation for customer notifications.

    curl --location --request POST '' \
    --header 'token: 0d25bdba-009b-47a9-a985-554692572b1e' \
    --header 'Content-Type: application/json' \
    --data-raw '{
     "identifiers": ["cloudentity"],
     "emailParams": {
         "templateId": "testnotification",
         "subject": "Subject"
     "emailContent": {
         "title": "title",
         "subtitle": "subtitle",
         "body": "E-mail body",
         "links": [""]


    Users in the selected organization (cloudentity in the above example) receive e-mails as specified in the emailParams and emailContent objects.

Having tried out the customer notification API, you might be interested in the following articles: