Authenticate to Identity Cloud REST API

Overview

The Identity Cloud REST API has three different authentication methods, depending on what you are trying to achieve:

  • Use an API key and secret for read-only operations.
    Examples: Identity Cloud monitoring and logging.

  • Use a session token for access management operations.
    Examples: Setting up authentication journeys or policies.

  • Use an access token for identity management operations or write operations.
    Examples: Configuring user profiles, roles, or assignments.

Summary of authentication methods

The following table summarizes the REST API endpoints and their different authentication methods:

REST endpoints Authentication method
  • /health

Not applicable (publicly accessible endpoint)

  • /monitoring

  • /logs

API key and secret:

  1. Create an API key and secret in the Identity Cloud Admin UI using an administrator account.

  2. Set the API key and secret as x-api-key and x-api-secret HTTP headers for each API request:

    x-api-key: <api-key>
    x-api-secret: <api-secret>
  • /am/*

Session token:

  1. Create a session token by authenticating a username and password:

    1. For administrative actions (for example, creating an OAuth 2.0 client), authenticate an Identity Cloud administrator username and password.

    2. For end-user actions, authenticate an end-user username and password.

  2. Set the session token as an HTTP header value for each API request. The HTTP header name is the tenant session cookie name (found in Tenant Settings > Global Settings > Cookie):

    <session-cookie-name>: <session-token>
  • /openidm/*

  • /.well-known/*

Access token:

  1. Create a session token by authenticating an Identity Cloud administrator username and password.

  2. Use the session token to create an OAuth 2.0 client with scope fr:idm:*.

  3. Create a realm user identity in the Identity Cloud Admin UI with authorization role openidm-admin.

  4. Create an access token using an OAuth 2.0 authorization grant flow. The grant flow needs to specify the credentials of the OAuth 2.0 client (step 2) and the realm user identity (step 3).

  5. Set the access token as a bearer token in the Authorization HTTP header for each API request:

    Authorization: Bearer <access-token>