ForgeRock Authentication API

openapi: 3.1.0
info:
  title: ForgeRock Access Management Access Requests Authentication API
  description: REST API for ForgeRock Access Management (AM) providing authentication, authorization, session management, and policy evaluation. Supports OAuth 2.0 and OpenID Connect flows, authentication trees/journeys, policy-based authorization decisions, and realm management.
  version: 7.3.0
  contact:
    name: ForgeRock
    url: https://www.forgerock.com
  license:
    name: Proprietary
    url: https://www.forgerock.com/terms
  x-provider: forgerock
  x-api: access-management
servers:
- url: https://{deployment}/am
  description: ForgeRock Access Management server
  variables:
    deployment:
      default: am.example.com
      description: The AM deployment hostname
security:
- ssoToken: []
- bearerAuth: []
tags:
- name: Authentication
  description: Authenticate users via authentication trees and modules
paths:
  /json/realms/root/realms/{realm}/authenticate:
    post:
      operationId: authenticate
      summary: ForgeRock Authenticate a user
      description: Initiates or continues an authentication session using a specified authentication tree (journey) or module. On each step, the server returns callbacks that the client must respond to. On success, returns a tokenId (SSO token).
      tags:
      - Authentication
      parameters:
      - $ref: '#/components/parameters/RealmPath'
      - name: authIndexType
        in: query
        description: Type of authentication index
        schema:
          type: string
          enum:
          - service
          - module
      - name: authIndexValue
        in: query
        description: Name of the authentication tree or module
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        description: Callback responses from a previous authentication step
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationCallbackRequest'
      responses:
        '200':
          description: Authentication step or success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /am/json/realms/root/realms/{realm}/authenticate:
    post:
      operationId: authenticateUser
      summary: ForgeRock Authenticate a user
      description: Initiates or continues an authentication journey (tree) in the specified realm. Returns callbacks that the client must respond to, or a tokenId on successful completion of the journey.
      tags:
      - Authentication
      parameters:
      - $ref: '#/components/parameters/RealmPath_2'
      - name: authIndexType
        in: query
        description: The type of authentication index to use (e.g., service, module)
        schema:
          type: string
          enum:
          - service
          - module
          - resource
          - level
      - name: authIndexValue
        in: query
        description: The value of the authentication index (e.g., the tree/journey name)
        schema:
          type: string
      - name: Accept-API-Version
        in: header
        required: true
        description: API version protocol header
        schema:
          type: string
          default: resource=2.0,protocol=1.0
      requestBody:
        description: Callback responses from a previous authentication step
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
      responses:
        '200':
          description: Authentication step response containing callbacks or a successful authentication result with tokenId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse_2'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
components:
  parameters:
    RealmPath:
      name: realm
      in: path
      required: true
      description: The realm name
      schema:
        type: string
        default: root
    ApiVersion:
      name: Accept-API-Version
      in: header
      required: true
      description: CREST API version protocol header
      schema:
        type: string
        default: resource=2.0,protocol=1.0
    RealmPath_2:
      name: realm
      in: path
      required: true
      description: The realm name (e.g., alpha, bravo)
      schema:
        type: string
        default: alpha
  schemas:
    AuthenticationResponse_2:
      type: object
      description: Authentication step result
      properties:
        authId:
          type: string
          description: Authentication session identifier for the next step
        tokenId:
          type: string
          description: SSO token ID returned on successful authentication
        successUrl:
          type: string
          description: URL to redirect to after successful authentication
        realm:
          type: string
          description: The realm in which authentication occurred
        callbacks:
          type: array
          description: Callbacks requiring user input
          items:
            $ref: '#/components/schemas/Callback'
    ErrorResponse_2:
      type: object
      description: Standard error response
      properties:
        code:
          type: integer
          description: HTTP status code
        reason:
          type: string
          description: HTTP status reason phrase
        message:
          type: string
          description: Detailed error message
    AuthenticationCallbackRequest:
      type: object
      description: Authentication callback response from client
      properties:
        authId:
          type: string
          description: Authentication session identifier
        callbacks:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              output:
                type: array
                items:
                  type: object
              input:
                type: array
                items:
                  type: object
    AuthenticationRequest:
      type: object
      description: Authentication callback response payload
      properties:
        authId:
          type: string
          description: Authentication session identifier from the previous step
        callbacks:
          type: array
          description: Completed callback responses
          items:
            $ref: '#/components/schemas/Callback'
    Callback:
      type: object
      description: An authentication callback
      properties:
        type:
          type: string
          description: The callback type
          examples:
          - NameCallback
          - PasswordCallback
          - ChoiceCallback
          - TextOutputCallback
        output:
          type: array
          description: Output values from the server
          items:
            type: object
            properties:
              name:
                type: string
              value:
                description: The output value
        input:
          type: array
          description: Input values to be provided by the client
          items:
            type: object
            properties:
              name:
                type: string
              value:
                description: The input value
    ErrorResponse:
      type: object
      description: Standard CREST error response
      properties:
        code:
          type: integer
        reason:
          type: string
        message:
          type: string
    AuthenticationResponse:
      type: object
      description: Authentication step or success result
      properties:
        authId:
          type: string
        tokenId:
          type: string
          description: SSO token on successful authentication
        successUrl:
          type: string
        realm:
          type: string
        callbacks:
          type: array
          items:
            type: object
  securitySchemes:
    ssoToken:
      type: apiKey
      in: header
      name: iPlanetDirectoryPro
      description: AM SSO token obtained from authentication
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token