openapi: 3.0.0
info:
  version: 1.0.0
  title: Authentication API
  description: >
    Quiqup uses **OAuth2 authentication** for secure API access.


    For more details on OAuth2 please refer to the [OAuth2
    Documentation](https://oauth.net/getting-started/).
  contact:
    email: support@quiqup.com
    name: QuiQup Support
servers:
  - url: https://platform-api.quiqup.com
    description: Production Server
  - url: https://platform-api.staging.quiqup.com
    description: Staging Server
paths:
  /oauth/token:
    post:
      tags:
        - Access Token
      summary: Get access token
      description: >
        ## Overview

        All our API endpoints support the **OAuth 2.0 authentication protocol**.


        ### How Authentication Works

        To start sending authenticated HTTP requests, follow these steps:


        1️⃣ **Obtain an OAuth2 Access Token**
           - Use your provided `client_id` and `client_secret` to request an access token.
           - Note: Staging and Production have different token expiration rules.

        2️⃣ **Token Expiration**
           - **Production**: Tokens are **valid for 7 days**.
           - **Staging**: Tokens expire **every 1 hour**.

        3️⃣ **Token Renewal**
           - Ensure your integration **handles token renewal properly**.
           - You can either **track the token expiry time** or **automatically request a new token** when your token has expired.

        ---


        ## Obtaining an Access Token


        ### POST /oauth/token


        🔹 **Description**

        Obtain an **OAuth2 access token** using the **Client Credentials** flow.


        🔹 **Token Expiry**

        - **Production:** `expires_in: 604800` (7 days)

        - **Staging:** `expires_in: 3600` (1 hour)


        ### 📥 Request Body Example

        ```json

        {
          "client_id": "your_client_id",
          "client_secret": "your_client_secret",
          "grant_type": "client_credentials"
        }

        ```


        ### 📤 Success Response Example

        ```json

        {
          "access_token": "245c47495152da4845b65f57facdd7c8b6765451e946b9faa4817c245a335110",
          "created_at": 1616571253,
          "expires_in": 604800,
          "token_type": "bearer"
        }

        ```


        ### 📤 Staging Response Example

        ```json

        {
          "access_token": "b76d4a126cf84959a8276f812321d598",
          "created_at": 1616571253,
          "expires_in": 3600,
          "token_type": "bearer"
        }

        ```


        ## Common Errors & Troubleshooting


        ### Invalid Client Credentials

        🔹 **HTTP 401 Unauthorized**

        - **Cause:** The provided `client_id` or `client_secret` is incorrect.

        - **Fix:** Verify credentials in your API settings.


        ### Invalid Grant Type

        🔹 **HTTP 400 Bad Request**

        - **Cause:** The `grant_type` must be `\"client_credentials\"`.

        - **Fix:** Ensure you pass `grant_type=client_credentials` in the
        request.


        ### Token Expired

        🔹 **HTTP 401 Unauthorized**

        - **Cause:** The access token has expired.

        - **Fix:** Request a new access token using `POST /oauth/token`.
      requestBody:
        content:
          application/json:
            examples:
              access_token:
                value:
                  client_id: your_client_id
                  client_secret: your_client_secret
                  grant_type: client_credentials
              refresh_token:
                value:
                  grant_type: refresh_token
                  refresh_token: your_refresh_token
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                refresh_token:
                  type: string
                  description: >
                    The refresh token to use to get a new access token. Only
                    used when the grant_type is `refresh_token`.
                grant_type:
                  type: string
                  default: client_credentials
                  enum:
                    - client_credentials
                    - refresh_token
          application/x-www-form-urlencoded:
            examples:
              access_token:
                value:
                  client_id: your_client_id
                  client_secret: your_client_secret
                  grant_type: client_credentials
              refresh_token:
                value:
                  grant_type: refresh_token
                  refresh_token: your_refresh_token
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                refresh_token:
                  type: string
                  description: >
                    The refresh token to use to get a new access token. Only
                    used when the grant_type is `refresh_token`.
                grant_type:
                  type: string
                  default: client_credentials
                  enum:
                    - client_credentials
                    - refresh_token
      responses:
        '200':
          description: >-
            The expires_in fields returns how many seconds the returned
            access_token is valid for. After that you will have to request this
            endpoint again in order to generate a new access_token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  created_at:
                    type: integer
                  expires_in:
                    type: integer
                  token_type:
                    type: string
                    default: bearer
                example:
                  access_token: >-
                    245c47495152da4845b65f57facdd7c8b6765451e946b9faa4817c245a335110
                  created_at: 1616571253
                  expires_in: 3600
                  token_type: bearer
              examples:
                default:
                  value:
                    access_token: >-
                      245c47495152da4845b65f57facdd7c8b6765451e946b9faa4817c245a335110
                    created_at: 1616571253
                    expires_in: 3600
                    token_type: bearer
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity
components: {}
