ForgeRock Authentication API

openapi: 3.2.0
info:
  title: Forgerock Authentication API
  contact:
    name: ForgeRock
    url: https://www.forgerock.com
  license:
    name: Proprietary
    url: https://www.forgerock.com/terms
  x-refined-note:
  - x-api differs across the merged source definitions and was not carried
  x-provider: forgerock
  version: '1.0'
  description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: forgerock-access-management-openapi.yml, forgerock-identity-cloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{deployment}/am
  description: ForgeRock Access Management server
  variables:
    deployment:
      default: am.example.com
      description: The AM deployment hostname
- url: https://{tenant}.forgeblocks.com
  description: ForgeRock Identity Cloud tenant
  variables:
    tenant:
      default: mycompany
      description: The tenant identifier for your Identity Cloud environment
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'
      security:
      - ssoToken: []
      - bearerAuth: []
    servers:
    - url: https://{deployment}/am
      description: ForgeRock Access Management server
      variables:
        deployment:
          default: am.example.com
          description: The AM deployment hostname
  /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'
      security:
      - bearerAuth: []
      - apiKeyAuth: []
    servers:
    - url: https://{tenant}.forgeblocks.com
      description: ForgeRock Identity Cloud tenant
      variables:
        tenant:
          default: mycompany
          description: The tenant identifier for your Identity Cloud environment
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:
    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
    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
    ErrorResponse:
      type: object
      description: Standard CREST error response
      properties:
        code:
          type: integer
        reason:
          type: string
        message:
          type: string
    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
    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
    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'
  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
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for tenant read-only operations. Used together with x-api-secret header.
x-refined-from:
- forgerock-access-management-openapi.yml
- forgerock-identity-cloud-openapi.yml