sitecore Authentication API

openapi: 3.2.0
info:
  title: Sitecore Authentication API
  version: '1.0'
  description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: sitecore-discover-api-openapi.yml, sitecore-ordercloud-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{subdomain}.rfksrv.com
  description: Sitecore Discover Production Server (subdomain URL)
  variables:
    subdomain:
      description: The customer-specific subdomain provided in the Discover CEC
      default: your-domain
- url: https://api.rfksrv.com
  description: Sitecore Discover Production Server (customer key URL)
- url: https://api.ordercloud.io/v1
  description: OrderCloud Production Server
security:
- bearerAuth: []
tags:
- name: Authentication
  description: Endpoints for obtaining access tokens used to authenticate API requests to Sitecore Discover.
paths:
  /account/1/access-token:
    put:
      operationId: renewAccessToken
      summary: Renew an access token
      description: Renews the access token used to authenticate requests to the Sitecore Discover API. Tokens must be refreshed periodically to maintain API access.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRenewRequest'
      responses:
        '200':
          description: Access token renewed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccessToken
      summary: Create an access token
      description: Creates a new access token for authenticating requests to the Sitecore Discover API using the provided API credentials.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
      responses:
        '200':
          description: Access token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://{subdomain}.rfksrv.com
      description: Sitecore Discover Production Server (subdomain URL)
      variables:
        subdomain:
          description: The customer-specific subdomain provided in the Discover CEC
          default: your-domain
    - url: https://api.rfksrv.com
      description: Sitecore Discover Production Server (customer key URL)
  /oauth/token:
    post:
      operationId: getAccessToken
      summary: Get an access token
      description: Obtains an OAuth 2.0 access token using the specified grant type. Supports password, client_credentials, and refresh_token grant types. The roles scope determines which resources and operations the token permits access to.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse_2'
        '400':
          $ref: '#/components/responses/BadRequest'
    servers:
    - url: https://api.ordercloud.io/v1
      description: OrderCloud Production Server
components:
  schemas:
    TokenCreateRequest:
      type: object
      description: Request body for creating a Discover access token
      required:
      - apiKey
      - customerId
      properties:
        apiKey:
          type: string
          description: The API key for the Sitecore Discover account
        customerId:
          type: string
          description: The customer identifier for the Discover account
    TokenResponse:
      type: object
      description: Authentication token response
      properties:
        accessToken:
          type: string
          description: The bearer access token for API authentication
        expiresIn:
          type: integer
          description: Token validity duration in seconds
        refreshToken:
          type: string
          description: Refresh token for renewing access
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        message:
          type: string
          description: A human-readable error message
        statusCode:
          type: integer
          description: The HTTP status code
        errors:
          type: array
          description: List of detailed error messages
          items:
            type: string
    TokenRenewRequest:
      type: object
      description: Request body for renewing an access token
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
          description: The refresh token from a previous authentication response
    TokenRequest:
      type: object
      description: OAuth 2.0 token request parameters
      required:
      - grant_type
      - client_id
      properties:
        grant_type:
          type: string
          description: The OAuth grant type
          enum:
          - password
          - client_credentials
          - refresh_token
        client_id:
          type: string
          description: The OrderCloud API client identifier
        username:
          type: string
          description: The user's username (required for password grant)
        password:
          type: string
          description: The user's password (required for password grant)
        scope:
          type: string
          description: Space-separated list of OrderCloud role scopes
        refresh_token:
          type: string
          description: The refresh token (required for refresh_token grant)
    TokenResponse_2:
      type: object
      description: OAuth 2.0 token response
      properties:
        access_token:
          type: string
          description: The bearer access token to include in API requests
        token_type:
          type: string
          description: The token type, always Bearer
          example: Bearer
        expires_in:
          type: integer
          description: Time in seconds until the token expires
        refresh_token:
          type: string
          description: Refresh token for obtaining a new access token
    ErrorDetail:
      type: object
      description: A single error detail
      properties:
        ErrorCode:
          type: string
          description: The machine-readable error code
        Message:
          type: string
          description: A human-readable description of the error
        Data:
          type: object
          description: Additional data about the error context
          additionalProperties: true
    ErrorResponse_2:
      type: object
      description: An error response body
      properties:
        Errors:
          type: array
          description: List of error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer access token obtained from the Sitecore Discover authentication endpoint. Include in the Authorization header.
x-refined-from:
- sitecore-discover-api-openapi.yml
- sitecore-ordercloud-api-openapi.yml