ForgeRock OAuth2 Clients API

openapi: 3.2.0
info:
  title: ForgeRock Identity Cloud REST OAuth2 Clients API
  description: REST API for managing identities, authentication, and authorization in ForgeRock Identity Cloud (PingOne Advanced Identity Cloud). Provides access management and identity management endpoints for Advanced Identity Cloud tenant environments, including authentication journeys, session management, managed object CRUD, OAuth 2.0 and OpenID Connect flows.
  version: 1.0.0
  contact:
    name: ForgeRock
    url: https://www.forgerock.com
  license:
    name: Proprietary
    url: https://www.forgerock.com/terms
  x-provider: forgerock
  x-api: identity-cloud
servers:
- url: https://{tenant}.forgeblocks.com
  description: ForgeRock Identity Cloud tenant
  variables:
    tenant:
      default: mycompany
      description: The tenant identifier for your Identity Cloud environment
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: OAuth2 Clients
  description: Manage OAuth 2.0 client registrations
paths:
  /am/oauth2/realms/root/realms/{realm}/authorize:
    get:
      operationId: authorizeOAuth2
      summary: ForgeRock OAuth 2.0 authorization endpoint
      description: Initiates an OAuth 2.0 authorization flow. Redirects the user agent to the authorization server for authentication and consent.
      tags:
      - OAuth2 Clients
      parameters:
      - $ref: '#/components/parameters/RealmPath'
      - name: client_id
        in: query
        required: true
        description: The OAuth 2.0 client identifier
        schema:
          type: string
      - name: response_type
        in: query
        required: true
        description: The OAuth 2.0 response type
        schema:
          type: string
          enum:
          - code
          - token
          - id_token
          - code token
          - code id_token
      - name: redirect_uri
        in: query
        required: true
        description: The URI to redirect to after authorization
        schema:
          type: string
          format: uri
      - name: scope
        in: query
        description: Space-delimited list of requested scopes
        schema:
          type: string
      - name: state
        in: query
        description: Opaque value to maintain state between request and callback
        schema:
          type: string
      responses:
        '302':
          description: Redirect to login or consent page
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /am/oauth2/realms/root/realms/{realm}/access_token:
    post:
      operationId: getAccessToken
      summary: ForgeRock OAuth 2.0 token endpoint
      description: Exchange an authorization code, refresh token, or client credentials for an access token.
      tags:
      - OAuth2 Clients
      parameters:
      - $ref: '#/components/parameters/RealmPath'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  description: The OAuth 2.0 grant type
                  enum:
                  - authorization_code
                  - client_credentials
                  - refresh_token
                  - password
                  - urn:ietf:params:oauth:grant-type:device_code
                code:
                  type: string
                  description: Authorization code (for authorization_code grant)
                redirect_uri:
                  type: string
                  description: Redirect URI (must match the authorization request)
                refresh_token:
                  type: string
                  description: Refresh token (for refresh_token grant)
                scope:
                  type: string
                  description: Requested scopes
                username:
                  type: string
                  description: Resource owner username (for password grant)
                password:
                  type: string
                  description: Resource owner password (for password grant)
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid grant or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '401':
          description: Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
components:
  schemas:
    OAuthErrorResponse:
      type: object
      description: OAuth 2.0 error response
      properties:
        error:
          type: string
          description: Error code
        error_description:
          type: string
          description: Human-readable error description
    TokenResponse:
      type: object
      description: OAuth 2.0 token response
      properties:
        access_token:
          type: string
          description: The access token
        token_type:
          type: string
          description: Token type (e.g., Bearer)
        expires_in:
          type: integer
          description: Token lifetime in seconds
        refresh_token:
          type: string
          description: Refresh token (if applicable)
        scope:
          type: string
          description: Granted scopes
        id_token:
          type: string
          description: OpenID Connect ID token (if applicable)
    ErrorResponse:
      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
  parameters:
    RealmPath:
      name: realm
      in: path
      required: true
      description: The realm name (e.g., alpha, bravo)
      schema:
        type: string
        default: alpha
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained from the token endpoint. Required for access management and identity management operations.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for tenant read-only operations. Used together with x-api-secret header.