Guide

REST APIs

Suggest Edits

REST APIs are an indispensable tool for Identity Cloud administrators. In some cases, REST APIs replicate or complement other Identity Cloud management tools. For example, you can promote a flow by using the Configuration API or you can promote a flow by using Console’s Registration Builder. In other cases, however, REST APIs are indispensable: there’s no way to create a Hosted Login token policy or enable and disabled the SIEM event delivery service without using an API call. Hosted Login, SIEM, custom providers, and the aptly-named API-based Identity Cloud implementation can only be managed by making API calls.

So what APIs are available to you, and what do those APIs actually do? For the answers, just keep reading.


Configuration API

Self-service tool for implementing login, registration, and profile management in your Identity Cloud implementation.

Clients and settings

  • Base URL: https://{identityDomain} /config/{appId}/clients; https://{identityDomain} /config/{appId}/settings
  • Supported authentication methods: Basic
  • Functionality available in Console : No
  • Description: Primarily used to manage API clients (referred to in Console as "properties"). It’s recommended that you use these operations rather than the Legacy client and settings operations.

Entity type

  • Base URL https://{identityDomain}/config/{appId}/entityTypes/{entityType}
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Manage Schemas section.
  • Description: View information about your entity types (user profile databases) and your entity type schemas. These operations are read-only. Use the Entity and entity type API to create or modify entity types.

Flows

Operations for working with Identity Cloud flows: JSON-formatted configuration files that help you define and manage such things as fields, forms, screens, and translations.

Subsections of this API include the following:

Flows

  • Base URL: https://{identityDomain}/config/{{appId}}/flows
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Registration Flows section in Registration Builder.
  • Description: Operations for managing flows. Flows are required regardless of whether you’re using Hosted Login, an API-based implementation of Identity Cloud, or the JavaScript SDK.

Fields

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/fields
  • Authentication methods supported Basic
  • Functionality available in Console Yes. Yes. See the Fields section in Registration Builder.
  • Description: Operations for managing Identity Cloud fields. Fields serve as a "bridge" between an Identity Cloud form and a user profile. For example, a form might have a City field (where users can enter their city of residence) that maps information to the primaryAddress.city user profile attribute.

Forms

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/forms
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Forms section in Registration Builder.
  • Description: Operations for managing Identity Cloud forms. Forms display user profile information to, and solicit user profile information from, end users.

Email templates

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/locales/{locale}/mailTemplates
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: API operations for managing transactional emails. Transactional emails are emails automatically sent by the Identity Cloud in response to certain events. For example, a transactional email is automatically sent any time a user clicks the Forgot password link and supplies their email address. These operations are the only way to manage transactional emails. You can modify the subject line and the body of an email, but you can’t create or delete emails.

Hosted Login migration

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/upgrades
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations that make a flow compatible with a specific version of Hosted Login. These operations are the only way to make a flow compatible with a specified version of Hosted Login.

Hosted Login links

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/links
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations for managing the links that appear on Hosted Login screens (for example, the Visit our help center link). Hosted Login provides three links (to your help center, your terms of service, and to your privacy policy) but, by default, those links don’t actually take users anywhere. To fix that, use these operations to change the link targets. These operations are the only way to change the URLs referenced by a Hosted Login link.

Hosted Login 2FA messages

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/locales/{locale}/2faMessages
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations for managing the email/SMS text messages used in two-factor authentication (2FA). Note that 2FA is only available in Hosted Login v2. These operations are the only way to modify two-factor authentication messages. You can modify message text, but you can’t create or delete messages.

Locales

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/locales
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations for managing locales and localized fields. Among other things, locales determine the language used when rendering Identity Cloud screens. There’s no operation for creating a locale: to add a locale simply create a translation that uses the appropriate language. Similarly, there’s no operation for deleting a locale. Instead, you would have to remove all the translations for that locale.

Strings

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/strings
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Fields section in Registration Builder.
  • Description: Operations for managing strings. Strings are localizable text elements that aren't tied to a specific form.

Screens

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/screens
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Screens section in Registration Builder.
  • Description: Operations for managing the screens displayed to Identity Cloud end users. These operations provide a way for you to create and delete screens. However, there is currently no way for you to manage when (or if) your screens are displayed. See your Identity Cloud representative for more information.

Translations

  • Base URL: https://{identityDomain}/config/{{appId}}/flows/{flow}/translations
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Fields section in Registration Builder.
  • Description: API operations for managing translations. Translations are exactly what the name implies: values for Identity Cloud text elements rendered in a language other than US English. Note, by default, Identity Cloud displays all text elements in US English (the only available locale). To render your screens in a different language, you will need to create translations for all the text elements used on those screens.
  • Additional Configuration API examples

Entity and entity type API

Operations for working with user profiles (entities) and with user profile databases (entity types).

Entities and user profiles

  • Base URL: https://{registrationDomain}
  • Supported authentication methods: Basic; janrain-signed
  • Functionality available in Console: Yes. See the Manage Profiles section.
  • Description: Operations for managing user accounts and user profiles.
  • Additional Entity and Entity Type API examples

Entity types and attributes

  • Base URL: https://{registrationDomain}
  • Supported authentication methods: Basic; janrain-signed
  • Functionality available in Console: Yes. See the Manage Schemas section.
  • Description: Operations for managing entity types (user profile databases) and the attributes that make up an entity type schema.
  • Additional Entity and Entity Type API examples

Access schemas

  • Base URL: https://{registrationDomain}
  • Supported authentication methods: Basic; janrain-signed
  • Functionality available in Console: No
  • Description: API operations for managing access schemas. An access schema defines the subset of attributes to which a client has read or write access. For example, you might allow help desk personnel to view – but not to change – a user’s email address or mobile device number.

Authentication API

Enables you to create and employ such things as authorization codes, access tokens, and verification codes. You can also use this API to log users on to a website or application, and by using either traditional logon or social logon. These are the APIs you’ll rely on if you choose to do an API-based implementation of Identity Cloud. At the same time, these operations are not intended for use with Hosted Login.

The Authentication API includes the following operations:

  • Access operations. Used for obtaining codes and tokens that enable you to perform specific actions on user profiles.

  • OAuth operations. Used to develop a custom authentication and registration experience without using Hosted Login, the JavaScript SDK, or the Mobile SDK. An API-only integration built with these operations supports social login and registration, traditional login and registration, profile management, social account merging, and password reset and email verification workflows.

Access tokens and codes

  • Base URL: https://{registrationDomain}/access; https://{registrationDomain}/oauth
  • Supported authentication methods: Varies depending on the operation.
  • Functionality available in Console: No
  • Description: Operations for obtaining access tokens and authorization codes.
  • Additional Authentication API examples

User profiles

  • Base URL: https://{registrationDomain}/access;
    https://{registrationDomain}/oauth
  • Supported authentication methods: None. However, operations require the caller to be an authenticated user.
  • Functionality available in Console: No
  • Description: Operations for updating user profiles.
  • Additional Authentication API examples

Webhooks v3 API

Operations available for use with Webhooks v3. Webhooks v3 provides near-real time notifications of events (such as user account creations or deletions) that take place in your organization.

Webhook subscriptions

  • Base URL: https://{identityDomain}/{customerId}/webhooks/subscriptions
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: Operations for managing Webhooks v3 subscriptions. Subscriptions (and, optionally, event filters) determine which events trigger notifications and which ones don’t. Use the /subscriptions/{subscriptionId} operation to manage webhook event filtering.

Webhook events

  • Base URL: https://{identityDomain}/{customerId}/webhooks/events
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: Operations for managing Webhooks v3 events. Includes an operation for scheduling the redelivery of events that, for whatever reason, couldn’t be delivered.

SIEM event delivery API

  • Base URL: https://{identityDomain}/config/applications/{appId}/eventdelivery/
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations available for use with the SIEM Event Delivery Service. SIEM (Security Information and Event Management) is a recognized standard for collecting, aggregating, and analyzing events within an IT organization.

Custom provider API

  • Base URL: https://{identityDomain}/{customerId}/v2/config/low/services/engage-v2/apps
  • Supported authentication methods: Token-based
  • Functionality available in Console: No. The ability to create custom providers is not available in the Social Login Dashboard, either.
  • Description: Operations for viewing information about your social login applications and for managing your custom providers. Custom providers enable you to use social login providers that haven't been predefined by Akamai. For example, you can configure Slack or Spotify as a social login identity provider (IdP) even though neither of those platforms ships as an out-of-the-box provider. In fact, you can configure almost any IdP as a custom provider as long as that IdP supports OAuth 2.0, OpenID Connect, or SAML 2.

Social API

Used to manage and configure social logins. The API consists of a number of different operations, including:

  • The Social login operations. Manage the social login process, including authentication, app settings, identity providers, and social profile data.

  • The App allow list operations. Manage an application's social login allow list. If the allow list is configured, only the domains included on the list can communicate with your social login application.

  • The Account mapping operations. Manage Social Login account mappings, the associations between a conventional user account and all of a user's social identities.

Tokens and authentication

  • Base URL: https://{socialLoginDomain/api/v2;
    https://{socialLoginDomain/signin
  • Supported authentication methods: Social login API key. Available on the Settings page in the Social Login Dashboard or saved as the rpx_app_id setting on Console’s Manage Application page.
    Functionality available in Console No
  • Description: Operations for managing social login authentications and tokens. To authenticate by using social login, a user starts by logging on to a social login IdP. If that login succeeds, the IdP issues the user an access token. In turn, that access token must be validated by Identity Cloud and the exchanged for an Identity Cloud access token.

Social login providers

  • Base URL: https://{socialLoginDomain/api/v2
  • Supported authentication methods: No authentication required
  • Functionality available in Console: No. However, this functionality is available in the Social Login Dashboard.
  • Description: Operations for managing the social login providers.
  • Additional Social API examples

Social login settings and configuration

  • Base URL: https://{socialLoginDomain/api/v2
  • Supported authentication methods: Social login API key. Available on the Settings page in the Social Login Dashboard or saved as the rpx_app_id setting on Console’s Manage Application page.
  • Functionality available in Console: No. However, this functionality is available in the Social Login Dashboard.
  • Description: Operations for managing social login configuration settings.

User profiles

  • Base URL: https://{socialLoginDomain/api/v2
  • Supported authentication methods: Social login API key. Available on the Settings page in the Social Login Dashboard or saved as the rpx_app_id setting on Console’s Manage Application page.
  • Functionality available in Console: Yes
  • Description: Operations for managing user profiles.

Legacy clients and settings API

Manage API clients and applications. As the word "legacy" implies, this API no longer represents the preferred way to programmatically manage API clients and applications. Instead, we recommend you use the Clients and Settings API for those purposes. The legacy API is still supported and the operations still work. However, the new API is easier to use, and adheres better to the standard REST API syntax and approach.

If you decide (perhaps for backwards compatibility reasons) to use the Legacy Clients and Settings API, that API offers the following operations:

  • Clients operations. Operations for creating, deleting, and editing API clients.
  • Settings operations. Operations for making changes to your registration configuration settings.

API clients

  • Base URL: https://{registrationDomain}/clients
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Manage Properties section.
  • Description: Operations for creating, deleting, and managing API clients.

Published settings

  • Base URL: https://{registrationDomain}/settings/widget
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: Operations for managing and publishing client and application settings. Applicable only for organizations using the JavaScript SDK.

Application and client settings

  • Base URL: https://{registrationDomain}/settings
  • Supported authentication methods: Basic
  • Functionality available in Console: Yes. See the Manage Application page. This functionality is also replicated in the Configuration API’s Clients and settings operations.
  • Description: API operations for managing API client and application settings.

Hosted Login, OpenID Connect, and OAuth APIs

Using the OpenID Connect Configuration APIs.

Tokens and authorization requests

  • Base URL: https://{identityDomain}/{customerId}/login/token
  • Supported authentication methods: Basic
  • Functionality available in Console: No
  • Description: API operations for managing Hosted Login tokens.

OpenID Connect clients

  • Base URL: https://{identityDomain}/{customerId}/config/clients
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: API operations for managing OpenID Connect clients, including public clients, confidential clients, and configuration clients.

Login policies

  • Base URL: https://{identityDomain}/{customerId}/config/loginPolicies
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: API operations for managing login policies. Login policies help manage the user login experience by doing such things as: specifying the exact path to the Capture domain and the user profile entity type, and defining the login URL for the associated directory. All OpenID Connect clients (public and confidential) must be associated with one (but only one) login policy.

Token policies

  • Base URL: https://{identityDomain}/{customerId}/config/tokenPolicies
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: API operations for managing Hosted Login token policies. Token policies are primarily used to specify token lifetimes.

OpenID Connect operations

  • Base URL: https://{identityDomain}/{customerId}/login;
    https://{identityDomain}/{customerId}/profiles/oidc
  • Supported authentication methods: Token-based
  • Functionality available in Console: No
  • Description: API operations for working with the OpenID Connect protocol.

Hosted Login operations

  • Base URL: https://{identityDomain}/{customerId}/auth-ui
  • Supported authentication methods: None. However, operations require the caller to be an authenticated user.
  • Functionality available in Console: No
  • Description: API operations for accessing a user profile and logging a user off from their Hosted Login session.

Updated almost 2 years ago