openapi: 3.0.3
info:
  title: OAuth
  version: 1.0.0
  description: |-
    Ideasoft APIs are authorized with the OAuth 2.0 authorization-code flow.
    The store owner grants your application at `/panel/auth`; you exchange the
    returned `code` for an access token at `/oauth/v2/token`.
    For a step-by-step walkthrough see the [Authentication](/getting-started/authentication) guide.
servers:
  - url: https://{host}
    description: Your store domain
    variables:
      host:
        default: your-store.myideasoft.com
        description: >-
          Your store domain: your myideasoft subdomain
          (your-store.myideasoft.com) or your own domain attached to the
          store (www.your-store.com)
tags:
  - name: OAuth
    description: OAuth 2.0 authorization-code flow endpoints.
paths:
  /panel/auth:
    get:
      operationId: oauth_authorize
      security: []
      tags: [OAuth]
      x-zudoku-playground-enabled: false
      summary: Authorization (authorize)
      description: |-
        Redirects the store owner to your application's authorization page.
        After approval the browser returns to `redirect_uri?code=...&state=...`.
        Scopes are not requested per call; they are fixed by the API
        definition the merchant created in the admin panel (Integrations → API).
      parameters:
        - name: client_id
          in: query
          required: true
          schema: { type: string }
          description: The client identifier issued to your application.
        - name: redirect_uri
          in: query
          required: true
          schema: { type: string, format: uri }
          description: The address to return to after authorization.
        - name: response_type
          in: query
          required: true
          schema: { type: string, enum: [code] }
          description: Always `code`.
        - name: state
          in: query
          required: false
          schema: { type: string }
          description: A random value for CSRF protection; verify it on return.
      responses:
        "302":
          description: Successful authorization; redirects to `redirect_uri?code=...&state=...`.
  /oauth/v2/token:
    post:
      operationId: oauth_token
      security: []
      tags: [OAuth]
      x-zudoku-playground-enabled: false
      summary: Token issue / refresh
      description: |-
        Issues the first token with the `authorization_code` grant and a new
        token with the `refresh_token` grant. `client_id`/`client_secret` may be
        sent in the body or via the HTTP Basic Authorization header.

        Required parameters per grant:
        - `authorization_code`: `client_id`, `client_secret`, `code`, `redirect_uri`
        - `refresh_token`: `client_id`, `client_secret`, `refresh_token`
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token]
                  description: Token grant method.
                client_id:
                  type: string
                  description: Client identifier (Basic auth header also accepted).
                client_secret:
                  type: string
                  description: Client secret.
                code:
                  type: string
                  description: "Required for the `authorization_code` grant; the code returned by the authorize step."
                redirect_uri:
                  type: string
                  format: uri
                  description: "Required for the `authorization_code` grant; must match the authorize step."
                refresh_token:
                  type: string
                  description: "Required for the `refresh_token` grant; the refresh token from a previous response."
      responses:
        "200":
          description: Token issued successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  expires_in: { type: integer, description: Token lifetime (seconds). }
                  token_type: { type: string, enum: [bearer] }
                  scope: { type: string, description: Space-separated scope list. }
                  refresh_token: { type: string }
              example:
                access_token: MmQyYzA0Zjc4YzA0OWY...
                expires_in: 3600
                token_type: bearer
                scope: catalog_read order_read
                refresh_token: NzQx...
        "400":
          description: Invalid request; returns the standard OAuth2 error body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  error_description: { type: string }
              example:
                error: invalid_grant
                error_description: Code doesn't exist or is invalid for the client
