openapi: 3.0.3
security: []
info:
  title: Keeta Basic API Reference
  version: v.1.0.0
  contact:
    name: Keeta Developer Website
    email: https://developers.mykeeta.com/
  description: >
    This API provides basic functionality for Keeta platform integration,
    including webhook configuration, authorization management, and OAuth token
    operations.
servers:
  - url: https://open.mykeeta.com/api/open/grocery
paths:
  /v1/oauth/token:
    post:
      operationId: generateAccessToken
      summary: Generate Access Token
      description: >
        Generate an OAuth 2.0 access token to include in the Authorization
        header of Partner API requests.


        **Rate Limiting:** This endpoint is rate-limited to one request per
        second per client ID. If you exceed this limit, you will receive a `429
        Too Many Requests` response.
      security:
        - Signature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grantType
                - clientId
                - clientSecret
              properties:
                grantType:
                  type: string
                  default: client_credentials
                  example: client_credentials
                  description: >-
                    The grant_type specifies the type of OAuth 2.0 grant being
                    used for obtaining the access token. Currently only
                    client_credentials is supported.
                clientId:
                  type: string
                  description: >-
                    The client_id is a unique identifier assigned to the client
                    application. This value is used to authenticate the
                    application requesting the access token. Ensure that this is
                    kept secure and not exposed publicly.
                clientSecret:
                  type: string
                  description: >-
                    The client_secret is a confidential value known only to the
                    client and the authorization server. It is used in
                    conjunction with the client_id to authenticate the client
                    application. Ensure that this is kept secure and not exposed
                    publicly.
      responses:
        '200':
          description: Successfully retrieved OAuth Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                access_token: eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9eyJ1dWlkIjoiVEVTVCJ9
                token_type: Bearer
                expires_in: 7200
        '400':
          description: >-
            Bad Request - The request parameters were invalid, missing, or
            malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
              examples:
                invalidRequest:
                  summary: Invalid request
                  value:
                    code: invalid_request
                    message: Invalid client credentials
                missingFieldFromRequest:
                  summary: Missing field from request
                  value:
                    code: invalid_request
                    message: client_id is required
                missingBody:
                  summary: Missing body
                  value:
                    code: invalid_request
                    message: Request body is missing
                invalidUrlEncodingInBody:
                  summary: Invalid URL encoding in body
                  value:
                    code: invalid_request
                    message: Invalid URL-encoded body
                unsupportedGrantType:
                  summary: Unsupported grant type
                  value:
                    code: unsupported_grant_type
                    message: Only 'client_credentials' grant type is supported
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: TOO_MANY_REQUESTS
                message: Rate limit exceeded for client <client-id>
        '500':
          description: Internal Server Error - Something went wrong on the server side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: INTERNAL_ERROR
                message: Internal Server Error
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9eyJ1dWlkIjoiVEVTVCJ9
          description: >-
            A short-lived JSON Web Token used to authenticate Partner API
            requests.
        tokenType:
          type: string
          example: Bearer
          description: The token type used in the Authorization header.
        expiresIn:
          type: integer
          example: 7200
          description: >-
            The access token lifetime in seconds. Cache and reuse the token
            until it expires, using this value as the cache time-to-live.
    OAuthErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INVALID_REQUEST
          description: OAuth error code.
        message:
          type: string
          example: Invalid client credentials
          description: Human-readable explanation of the OAuth error.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INTERNAL_ERROR
          description: Machine-readable error code.
        message:
          type: string
          example: Internal Server Error
          description: Human-readable error message.
    AuthorizedResourceResponse:
      type: object
      description: Merchant authorization information.
      properties:
        chainId:
          type: string
          example: '4323'
          description: Chain ID of the authorized vendors.
        chainName:
          type: string
          example: GUI JI
          description: Chain name of the authorized vendors.
        authorizedVendors:
          type: array
          description: List of authorized vendors.
          items:
            $ref: '#/components/schemas/AuthorizedShop'
    AuthorizedShop:
      type: object
      properties:
        vendorId:
          type: string
          example: '145541'
          description: Vendor ID.
        name:
          type: string
          example: Downtown Vendor
          description: Vendor name.
        address:
          type: string
          example: 123 Main Street
          description: Vendor address.
        longitude:
          type: string
          example: '114.057868'
          description: Vendor longitude.
        latitude:
          type: string
          example: '22.543099'
          description: Vendor latitude.
    CallbackErrorResponse:
      type: object
      properties:
        title:
          type: string
          example: Unexpected error
          description: Human-readable error title.
        status:
          type: integer
          format: int32
          example: 500
          description: Numeric error status supplied by the callback service.
  responses:
    CallbackBadRequest:
      description: The callback request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallbackErrorResponse'
          example:
            title: Unexpected error
            status: 500
    CallbackForbidden:
      description: The authenticated request violated an authorization rule.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallbackErrorResponse'
          example:
            title: Unexpected error
            status: 500
    CallbackNotFound:
      description: The requested callback resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallbackErrorResponse'
          example:
            title: Unexpected error
            status: 500
    CallbackUnavailable:
      description: >-
        The callback service is unavailable, under maintenance, or outside its
        operating window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallbackErrorResponse'
          example:
            title: Unexpected error
            status: 500
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials used by partner applications.
      flows:
        clientCredentials:
          tokenUrl: >-
            https://api-docs.mykeeta.com/apis/yhsu3hu21ch23yabx4xuuuq7/basic/endpoints/generateaccesstoken
          scopes: {}
    Signature:
      type: apiKey
      description: >-
        To enhance overall security, Keeta requires a signature in the Header
        when making requests to Keeta. Please refer to [Authorization
        Guide](https://api-docs.mykeeta.com/apis/yhsu3hu21ch23yabx4xuuuq7/docs/auth)
        for details.
      in: header
      name: Signature
