search
getting started

Service App

QUICK START
In this quick start you’ll:

  • Create a service app in the administrative console.
  • Use the app to get an access token.
  • Use the access token to call the Management API user endpoint.


Step 1: Create the App

1a. Sign in to the ForgeRock Identity Cloud Express Console, at http://{your-organization-name}.forgerock.com.

1b. Select Applications > New Application, and select Service.


application console

Step 2: Configure the App

Before you can use the service app, you’ll need an access token, available through the Authentication API. With that token, you can use the Management API to create users through the users endpoint. To get an access token, create a service app.

2a. In the Express console, go to Applications > New Application and create a Service App.

2b. Select Save Application and make a copy of the Client ID and Client Secret that appears.


service app

Step 3 : Obtain an Access Token

When you make a call through your app to get an access token, include the API scopes you want for the Management API. Since we are using a service app, there are no users, and therefore no OIDC scopes. Learn more about scopes and tokens.

3a. Select the API Scopes tab and review configured API scopes. They are set to allow you to read, create, and update users.


Service app scopes

3b. Base64-encode your Client ID and Client Secret using the following command:

content_copy COPY

echo -n CLIENT_ID:CLIENT_SECRET | base64

In the following REST call, replace:

  • {BASE_64_ENCODED_STRING}
  • {tenantName}

3c. Run the custom command in your terminal.

content_copy COPY

curl -X POST \
https://openam-{tenantName}.forgeblocks.com/am/oauth2/access_token \
-H 'Authorization: Basic {BASE_64_ENCODED_STRING}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'scope=user.read%20user.create%20user.update&grant_type=client_credentials'

The output includes an access_token, which will allow you to read (user.read), create (user.create), and update (user.update) users.

Step 4: Call the Management API

4a. Use the Management API to create a user based on the new access_token. In the following command, substitute your values for:

  • {ACCESS_TOKEN}
  • {tenantName}

4b. Then run the command in the terminal.

content_copy COPY

curl -X POST \
https://api-{tenantName}.forgeblocks.com/v1/users \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'cache-control: no-cache' \
-d '{
    "externalId": "701985",
    "userName": "[email protected]",
    "accountVerified": true,
    "name": {
      "formatted": "Ms. Barbara J Jensen, III",
      "familyName": "Jensen",
      "givenName": "Barbara",
      "middleName": "Jane",
      "honorificPrefix": "Ms.",
      "honorificSuffix": "III"
    },
    "displayName": "Babs Jensen",
    "nickName": "Babs",
    "profileUrl": "https://signin.example.com/bjensen",
    "emails": [
      {
        "value": "[email protected]",
        "type": "work",
        "primary": true,
        "verified": true
      },
      {
        "value": "[email protected]",
        "type": "home",
        "verified": false
      }
    ],
    "addresses": [
      {
        "type": "work",
        "streetAddress": "6925 Hollywood Blvd",
        "locality": "Hollywood",
        "region": "CA",
        "postalCode": "90028",
        "country": "US",
        "formatted": "6925 Hollywood Blvd\nHollywood, CA 90028 USA",
        "primary": true
      },
      {
        "type": "home",
        "streetAddress": "2800 E Observatory Rd",
        "locality": "Los Angeles",
        "region": "CA",
        "postalCode": "90027",
        "country": "US",
        "formatted": "2800 E Observatory Rd\nLos Angeles, CA 90027 USA"
      }
    ],
    "phoneNumbers": [
      {
        "value": "555-555-5555",
        "type": "work"
      },
      {
        "value": "555-555-4444",
        "type": "mobile"
      }
    ],
    "userType": "Customer",
    "title": "Master Carpenter",
    "preferredLanguage": "en-US",
    "locale": "en-US",
    "timezone": "America/Los_Angeles",
    "active": true,
    "password": "Passwordy6!"
  }'


That’s it! Review the user entry in the Express console. The console doesn’t show every user detail. You can use the Management API to review, add, or revise data for this or all users.

Where to Go From Here

  1. Navigate to the REST APIs page. Download the Postman collection.

  2. Update the user you just created. Find the id returned from the REST call you ran to create the user.

  3. Try running REST calls on other users endpoints.

  4. If you want different access privileges, create a new access_token with desired scopes. You’re limited to the scopes configured for your app. So find your app at https://ui-(tenantName).forgeblocks.com/apps/, and review the associated API Scopes tab.