Protected self-services
17.2.5. Protected REST APIs (self-services)

Protected self-service REST APIs are used by end-users to modify their user account data. Typical examples are: modification of address information or authentication token self-management.

There are two types of protected APIs:

  • Flow-based self-services
  • All APIs under: /protected/self-service
  • These are flow-based self-services with all the advantages of flows.
  • Access- and authorization conditions are used to protect the end-points. They are configured directly in the flow or service configs.
  • Favor these services over the session-less endpoints.
  • Session-less end-points
  • All APIs under: /protected/my (plus the /secret-question end-point directly under /protected).
  • These are non-flowbased services and session-less.
  • Authentication and authorization for these services are configured using the properties in the configuration group API Access Control.
  • For further information, see 17.2.5.7. Session-less protected REST APIs.
  • If possible, use the corresponding flow-based self-services instead.

Flow-based self-service REST APIs

All flow-based self-service APIs have the following properties:

Authentication
To access the protected self-services the user must be authenticated.
Flow Selection
Protected self-service flows do not support the concept of a "default flow". It is therefore mandatory to start every flow with a REST call that contains the name of the flow and that uses the "select" method.
Authorization
Protected self-service flows provide optional flow steps to validate changes before they are persisted. This can be used to protect security-relevant changes against abuse or to verify a change with the user before it is applied.
Pre-Conditions
Protected self-service flows may require pre-conditions to be met. This is especially useful if a flow requires authorization to ensure an authorization-capable means of authentication is configured on the user account.