Canoe Intelligence Authentication API

openapi: 3.2.0
info:
  title: Canoe Intelligence Authentication API
  version: '1.0'
  description: 'Operations tagged Authentication across 3 of this provider''s published API definitions: canoe-intelligence-api-docs-v1-original.yaml, canoe-intelligence-api-openapi-original.json, canoe-intelligence-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.canoesoftware.com
  description: Production API
tags:
- name: Authentication
  description: ''
paths:
  Authentication Error Responses:
    get:
      tags:
      - Authentication
      summary: null
      description: "<h3>Authentication Error Responses</h3>\n\n<p>When authentication fails, Canoe's API returns detailed error responses to help you diagnose and resolve issues. All authentication errors follow a consistent format with the following fields:</p>\n\n<table><thead>\n    <tr>\n        <th>Field</th>\n        <th>Type</th>\n        <th>Description</th>\n    </tr>\n    </thead><tbody>\n    <tr>\n        <td>error_code</td>\n        <td>String</td>\n        <td>A machine-readable error code that identifies the specific type of error (e.g., <code>INVALID_CREDENTIALS</code>, <code>MALFORMED_JWT</code>, <code>RATE_LIMIT_EXCEEDED</code>)</td>\n    </tr>\n    <tr>\n        <td>error_description</td>\n        <td>String</td>\n        <td>A human-readable description of what went wrong</td>\n    </tr>\n    <tr>\n        <td>hint</td>\n        <td>String</td>\n        <td>Actionable guidance on how to resolve the error</td>\n    </tr>\n    </tbody></table>\n\n<h4>Common Authentication Errors</h4>\n\n<p><strong>Invalid Credentials (400)</strong></p>\n<pre><code>{\n    \"error_code\": \"INVALID_CREDENTIALS\",\n    \"error_description\": \"The user credentials were incorrect\",\n    \"hint\": \"Please verify your client_id and client_secret are correct\"\n}</code></pre>\n\n<p><strong>Malformed JWT Token (401)</strong></p>\n<pre><code>{\n    \"error_code\": \"MALFORMED_JWT\",\n    \"error_description\": \"Token structure is invalid\",\n    \"hint\": \"JWT tokens must have format: header.payload.signature\"\n}</code></pre>\n\n<p><strong>Rate Limit Exceeded (429)</strong></p>\n<pre><code>{\n    \"error_code\": \"RATE_LIMIT_EXCEEDED\",\n    \"error_description\": \"Too many failed authentication attempts\",\n    \"retry_after\": 60,\n    \"hint\": \"Please check your credentials and wait 60 seconds before trying again\"\n}</code></pre>\n\n<aside class=\"warning\">\n    <strong>Rate Limiting:</strong> To protect against brute-force attacks, Canoe implements rate limiting on authentication endpoints. If you receive a 429 error, wait for the time specified in the <code>retry_after</code> field before attempting to authenticate again.\n</aside>\n\n<aside class=\"notice\">\n    <strong>Best Practices:</strong>\n    <ul>\n        <li>Store your client credentials securely and never commit them to version control</li>\n        <li>Implement exponential backoff when retrying failed authentication requests</li>\n        <li>Monitor the <code>error_code</code> field in your error handling to respond appropriately to different error types</li>\n    </ul>\n</aside>\n"
      operationId: AuthenticationErrorResponses
  Managing OAuth Clients:
    get:
      tags:
      - Authentication
      summary: null
      description: "<p>To verify incoming API requests, Canoe's APIs use access tokens.</p>\n<p>Canoe API users may <a href=\"#managing-oauth-clients\">create and manage their OAuth Client</a>, and use the <code>Client ID</code> and <code>Client Secret</code> to request an authorization code and access token.</p>\n<p>Canoe API users can also use the <code class=\"prettyprint\">/v1/tokens</code> <a href=\"#password-grant-tokens\">endpoint</a> to manage the access tokens. To authenticate to the <code class=\"prettyprint\">/v1/tokens</code> endpoint, you will need API user credentials. This is one of the few API endpoints where you will need to use your user credentials; most other endpoints are authenticated through access tokens.</p>\n<aside class=\"notice\">\n    Note: An access token issued from Canoe will expire in 24 hours.\n</aside>\n<p>Once you have an access token, you can authenticate to Canoe's API endpoints. Pass the access token in the request header in the format <code class=\"prettyprint\">Authorization: Bearer {token}</code>, where <code class=\"prettyprint\">{token}</code> is your newly created personal access token.</p>\n<p>For example, if your newly created access token is \"eyJ0eXAiOiJKV1QiLCJhbG\", your header should look like \"Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG\"</p>\n<p>If you are using Postman Collection for testing purpose, you could follow the steps here: <a href=\"https://learning.getpostman.com/docs/postman/sending_api_requests/authorization/#bearer-token\" target=\"_blank\"><u>Authorization - Bearer Token</u></a></p>\n<aside class=\"notice\">\n    Note: Sometimes, you want to give API access only to some specific IP addresses. Please contact us to enable that.\n</aside>\n\n<p>Developers building applications that need to interact with Canoe's API need to first register their application by creating a Client account. Typically, this consists of providing the name of their application and a URL that your application can redirect to after users approve their request for authorization. When a Client is created, it will be issued a <code>Client ID</code> and <code>Client Secret</code>. These values will be used when requesting access tokens from your application. </p>\n\n<p>Canoe API users can create and manage their OAuth Clients through the <a href=https://client.canoesoftware.com/api_configuration target=\"_blank\"><u>API Configuration Dashboard</u></a>.</p>\n"
      operationId: ManageAuthClient
  Requesting Tokens - Authorization Code:
    post:
      tags:
      - Authentication
      summary: null
      description: '/oauth/token


        <p>Once a client has been created, you may use the <code>Client ID</code> and <code>Client Secret</code> to request an

        authorization code and access token from your application. First, your application should make a redirect request to

        Canoe''s <code>oauth/authorize</code> route (see examples on the right panel)</p>


        <p>When receiving authorization requests, Canoe will ask users to approve or deny the authorization request. If users approve the request, they will be redirected back to the <code>redirect_uri</code> that was specified by the application that requested access (your application). The <code>redirect_uri</code> must match the <code>redirect</code> URL that was specified when the client was created.</p>

        <p>If the user approves the authorization request, they will be redirected back to the consuming application with the authorization code. The consumer should then issue a <code>POST</code> request to Canoe to request an access token. The request should include the authorization code that was issued by Canoe when the user approved the authorization request. See examples on the right panel and the parameters for the <code>POST</code> request below.</p>

        '
      operationId: RequestingTokensAuthCodes
      parameters:
      - name: grant_type
        in: body
        description: The grant_type parameter must be set to "authorization_code".
        required: true
        schema:
          type: string
          example:
            grant_type: authorization_code
      - name: client_id
        in: body
        description: Your Application's Client ID.
        required: true
        schema:
          type: string
          example:
            client_id: client-id
      - name: client_secret
        in: body
        description: Your Application's Client Secret.
        required: true
        schema:
          type: string
          example:
            client_secret: your_client_secret
      - name: redirect_uri
        in: body
        description: Your Application's redirect URL. <b>It must match the redirect URL that was specified when the client was created.</b>
        required: true
        schema:
          type: string
          example:
            redirect_uri: https://your-application.com/callback
      - name: code
        in: body
        description: The authorization code issued by Canoe when the user approved the authorization request.
        required: true
        schema:
          type: string
          example:
            code: code
      requestBody:
        content:
          application/json:
            schema:
              type: string
            examples:
              bash:
                description: "-\n      #Please go to the link below to authorize access.\n      https://api.canoesoftware.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code\n\n      #Please copy the 'YOUR_AUTHORIZATION_CODE' in the redirect url(YOUR_REDIRECT_URI?code=YOUR_AUTHORIZATION_CODE) after approving access\n      curl -X POST \"https://api.canoesoftware.com/oauth/token\" \\\n          -H \"Accept: application/json\" \\\n          -H \"X-Requested-With: XMLHttpRequest\" \\\n          -H \"Content-Type: application/x-www-form-urlencoded\" \\\n          -d \"grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\"\n"
                summary: Bash
              Javascript:
                description: "-\n      const readline = require('readline');\n      const rl = readline.createInterface({\n          input: process.stdin,\n          output: process.stdout\n      });\n      const client_id = 'client_id';\n      const client_secret = 'client_secret';\n      const redirect_uri = 'https://your-application.com/callback';\n      const url = new URL(\"https://api.canoesoftware.com/oauth/authorize\");\n      let params = {\n          \"client_id\": client_id,\n          \"client_secret\": client_secret,\n          \"redirect_uri\": redirect_uri,\n          \"response_type\": 'code',\n      };\n      Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));\n      console.log('Please go to %s and authorize access.', url)\n      rl.question('Enter the authorization code returned in the callback URL.', (answer) => {\n          let code = answer;\n          let headers = {\n              \"Accept\": \"application/json\",\n              \"X-Requested-With\": \"XMLHttpRequest\",\n              \"Content-Type\": \"application/json\",\n          }\n          let body = {\n              'grant_type': \"authorization_code\",\n              'client_id': client_id,\n              'client_secret': client_secret,\n              'redirect_uri': redirect_uri,\n              'code': code,\n          };\n          axios.request('https://api.canoesoftware.com/oauth/token', {\n              method: \"POST\",\n              headers: headers,\n              data: body\n          })\n              .then(response => {\n                  console.log(response.data)\n              })\n              .catch(error => {\n                  console.log(error);\n              })\n          rl.close();\n      });\n"
                summary: JavaScript
              PHP:
                description: "-\n      Route::get('/redirect', function () {\n          $query = http_build_query([\n          'client_id' => 'client-id',\n          'redirect_uri' => 'https://your-application.com/callback',\n          'response_type' => 'code',\n          'scope' => '',\n          ]);\n          return redirect('https://api.canoesoftware.com/oauth/authorize?'.$query);\n      });\n\n\n      Route::get('/callback', function (Request $request) {\n          $http = new GuzzleHttp\\Client;\n          $response = $http->post('https://api.canoesoftware.com/oauth/token', [\n              'form_params' => [\n                  'grant_type' => 'authorization_code',\n                  'client_id' => 'client-id',\n                  'client_secret' => 'client-secret',\n                  'redirect_uri' => 'https://your-application.com/callback',\n                  'code' => $request->code,\n              ],\n          ]);\n          return json_decode((string) $response->getBody(), true);\n      });\n"
                summary: PHP
              Python:
                description: "-\n      #This sample requires python OAuth library requests_oauthlib\n\n      from requests_oauthlib import OAuth2Session\n      import json\n      client_id = \"client_id\"\n      client_secret = \"client_secret\"\n      redirect_uri = \"https://your-application.com/callback\"\n      oauth = OAuth2Session(client_id, redirect_uri=redirect_uri)\n      authorization_url, state = oauth.authorization_url('https://api.canoesoftware.com/oauth/authorize')\n      print('Please go to {} and authorize access.'.format(authorization_url))\n      authorization_response = input('Enter the full callback URL')\n      token = oauth.fetch_token(\n      'https://api.canoesoftware.com/oauth/token',\n      authorization_response=authorization_response,\n      client_id=client_id,\n      client_secret=client_secret)\n      print(token)\n"
                summary: Python
              CSharp:
                description: "-\n      using System;\n      using System.Threading;\n      using RestSharp;\n\n      var client_id = \"your_client_id\";\n      var client_secret = \"your_client_secret\";\n      var redirect_uri = \"your_redirect_url\";\n      var baseUrl = \"https://api.canoesoftware.com\";\n      var client = new RestClient(baseUrl);\n      var request = new RestRequest(string.Format(\"/oauth/authorize?response_type=code&client_id={0}&client_secret={1}&redirect_uri={2}\",client_id, client_secret, System.Web.HttpUtility.UrlEncode(redirect_uri)), Method.Get);\n      var url = client.BuildUri(request).ToString();\n      //The below workflow assumes the user does not have control over the redirect_uri\n      //If the redirect_uri goes to your application, you can request a token by exchanging the authorization code directly\n      string auth_code = null;\n      var ps = new System.Diagnostics.ProcessStartInfo(url)\n      {\n          UseShellExecute = true,\n          Verb = \"open\"\n      };\n      //This will open your default browser\n      System.Diagnostics.Process.Start(ps);\n      //Please copy the 'THE_AUTHORIZATION_CODE' in the redirect url(YOUR_REDIRECT_URI?code=THE_AUTHORIZATION_CODE) after approving access \n      Console.WriteLine(\"Enter the authorization code returned in the callback URL:\");\n      string code = Console.ReadLine();\n      request = new RestRequest(\"/oauth/token\", Method.Post);\n      request.AddHeader(\"Accept\", \"application/json\");\n      request.AddHeader(\"X-Requested-With\", \"XMLHttpRequest\");\n      request.AddParameter(\"grant_type\", \"authorization_code\");\n      request.AddParameter(\"code\", code);\n      request.AddParameter(\"client_id\", client_id);\n      request.AddParameter(\"client_secret\", client_secret);\n      request.AddParameter(\"redirect_uri\", redirect_uri);\n      var response = client.Execute(request);\n      Console.WriteLine(response.Content);\n"
                summary: CSharp
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorizationCode'
  Requesting Tokens - Refresh Token:
    post:
      tags:
      - Authentication
      summary: null
      description: '/oauth/token


        <p>Users can refresh their access tokens via the refresh token that was provided to them when the access token was issued.</p>

        <p>Users should issue a <code>POST</code> request to Canoe to request an access token. See examples on the right panel and the parameters for the <code>POST</code> request below.</p>

        '
      operationId: RequestingTokensRefreshToken
      parameters:
      - name: grant_type
        in: body
        description: refresh_token.
        required: true
        schema:
          type: string
          example:
            grant_type: refresh_token
      - name: client_id
        in: body
        description: Your Application's Client ID.
        required: true
        schema:
          type: string
          example:
            client_id: your_client_id
      - name: client_secret
        in: body
        description: Your Application's Client Secret.
        required: true
        schema:
          type: string
          example:
            client_secret: your_client_secret
      - name: refresh_token
        in: body
        description: The refresh_token issued by Canoe when the access token was issued.
        required: true
        schema:
          type: string
          example:
            refresh_token: def50200a24fe7672ce8653724d90090ca68fc4729a04b1051b2c8
      requestBody:
        content:
          application/json:
            schema:
              type: string
            examples:
              bash:
                description: "-\n      curl -X POST \"https://api.canoesoftware.com/oauth/token\" \\\n      -H \"Accept: application/json\" \\\n      -H \"X-Requested-With: XMLHttpRequest\" \\\n      -H \"Content-Type: application/x-www-form-urlencoded\" \\\n      -d \"grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&refresh_token=your_refresh_token\"\n"
                summary: Bash
              Javascript:
                description: "-\n      const url = new URL(\"https://api.canoesoftware.com/oauth/token\");\n      let headers = {\n          \"Accept\": \"application/json\",\n          \"X-Requested-With\": \"XMLHttpRequest\",\n          \"Content-Type\": \"application/json\",\n      }\n      let body = {\n        'grant_type': \"refresh_token\",\n        'client_id': client_id,\n        'client_secret': client_secret,\n        'refresh_token': refresh_token,\n      }\n      fetch(url, {\n          method: \"POST\",\n          headers: headers,\n          body: body\n      }).then(response => response.json()) .then(json => console.log(json));\n"
                summary: JavaScript
              PHP:
                description: "-\n      $client = new \\GuzzleHttp\\Client();\n      $response = $client->post(\"https://api.canoesoftware.com/oauth/token\", [\n          'headers' => [\n              \"Accept\" => \"application/json\",\n              \"X-Requested-With\" => \"XMLHttpRequest\",\n              \"Content-Type\" => \"application/json\",\n          ],\n          'json' => [\n              'grant_type'=> \"refresh_token\",\n              'client_id'=> \"your_client_id\",\n              'client_secret'=> \"your_client_secret\",\n              'refresh_token'=> \"your_refresh_token\",\n          ],\n      ]);\n      $body = $response->getBody();\n      print_r(json_decode((string) $body));\n"
                summary: PHP
              Python:
                description: "-\n      import requests\n      import json\n\n      url = \"https://api.canoesoftware.com/oauth/token\"\n      headers = {\n          \"Accept\": \"application/json\",\n          \"X-Requested-With\": \"XMLHttpRequest\",\n          \"Content-Type\": \"application/json\",\n      }\n      body = {\n          \"grant_type\": \"refresh_token\",\n          \"client_id\": \"your_client_id\",\n          \"client_secret\": \"your_client_secret\",\n          \"refresh_token\": \"def50200a24fe7672ce8653724d90090ca68fc4729a04b1051b2c8\"\n      }\n\n      response = requests.post(url, json.dumps(body), headers=headers, )\n      parsed = json.loads(response.text)\n      print(json.dumps(parsed, indent=4))\n"
                summary: Python
              CSharp:
                description: "-\n      using RestSharp;\n\n      var client = new RestClient(\"https://api.canoesoftware.com/\");\n      var request = new RestRequest(\"oauth/token\", Method.Post);\n      request.AddHeader(\"Accept\", \"application/json\");\n      request.AddHeader(\"X-Requested-With\", \"XMLHttpRequest\");\n      request.AddHeader(\"Content-Type\", \"application/json\");\n      request.AddParameter(\"grant_type\",\"refresh_token\");\n      request.AddParameter(\"client_id\",\"your_client_id\");\n      request.AddParameter(\"client_secret\",\"your_client_secret\");\n      request.AddParameter(\"refresh_token\",\"your_refresh_token\");\n      var response = client.Execute(request);\n      Console.WriteLine(response.Content);\n"
                summary: CSharp
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorizationCode'
  Requesting Tokens - Client Credentials:
    post:
      tags:
      - Authentication
      summary: null
      description: '/oauth/token


        <p>Once a client has been created, you may use the <code>Client ID</code> and <code>Client Secret</code> to request an

        to request an access token. Access tokens provide access to all other endpoints within the API.</p>

        '
      operationId: RequestingTokensClientCredentials
      parameters:
      - name: grant_type
        in: body
        description: The grant_type parameter must be set to "client_credentials".
        required: true
        schema:
          type: string
          example:
            grant_type: client_credentials
      - name: client_id
        in: body
        description: Your Application's Client ID.
        required: true
        schema:
          type: string
          example:
            client_id: client_credentials
      - name: client_secret
        in: body
        description: Your Application's Client Secret.
        required: true
        schema:
          type: string
          example:
            client_secret: your_client_secret
      requestBody:
        content:
          application/json:
            schema:
              type: string
            examples:
              bash:
                description: "-\n      curl -X POST \"https://api.canoesoftware.com/oauth/token\" \\\n      -H \"Accept: application/json\" \\\n      -H \"X-Requested-With: XMLHttpRequest\" \\\n      -H \"Content-Type: application/x-www-form-urlencoded\" \\\n      -d \"grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret\"\n"
                summary: Bash
              Javascript:
                description: "-\n      const url = new URL(\"https://api.canoesoftware.com/oauth/token\");\n      let headers = {\n          \"Accept\": \"application/json\",\n          \"X-Requested-With\": \"XMLHttpRequest\",\n          \"Content-Type\": \"application/json\",\n      }\n      let body = {\n        'grant_type': \"client_credentials\",\n        'client_id': client_id,\n        'client_secret': client_secret,\n      }\n      fetch(url, {\n          method: \"POST\",\n          headers: headers,\n          body: body\n      }).then(response => response.json()) .then(json => console.log(json));\n"
                summary: JavaScript
              PHP:
                description: "-\n      $client = new \\GuzzleHttp\\Client();\n      $response = $client->post(\"https://api.canoesoftware.com/oauth/token\", [\n          'headers' => [\n              \"Accept\" => \"application/json\",\n              \"X-Requested-With\" => \"XMLHttpRequest\",\n              \"Content-Type\" => \"application/json\",\n          ],\n          'json' => [\n              'grant_type'=> \"client_credentials\",\n              'client_id'=> \"your_client_id\",\n              'client_secret'=> \"your_client_secret\",\n          ],\n      ]);\n      $body = $response->getBody();\n      print_r(json_decode((string) $body));\n"
                summary: PHP
              Python:
                description: "-\n      import requests\n      import json\n\n      url = \"https://api.canoesoftware.com/oauth/token\"\n      headers = {\n          \"Accept\": \"application/json\",\n          \"X-Requested-With\": \"XMLHttpRequest\",\n          \"Content-Type\": \"application/json\",\n      }\n      body = {\n          \"grant_type\": \"client_credentials\",\n          \"client_id\": \"client_credentials\",\n          \"client_secret\": \"your_client_secret\",\n      }\n\n      response = requests.post(url, json.dumps(body), headers=headers, )\n      parsed = json.loads(response.text)\n      print(json.dumps(parsed, indent=4))\n"
                summary: Python
              CSharp:
                description: "-\n      using RestSharp;\n\n      var client = new RestClient(\"https://api.canoesoftware.com/\");\n      var request = new RestRequest(\"oauth/token\", Method.Post);\n      request.AddHeader(\"Accept\", \"application/json\");\n      request.AddHeader(\"X-Requested-With\", \"XMLHttpRequest\");\n      request.AddHeader(\"Content-Type\", \"application/json\");\n      request.AddParameter(\"grant_type\",\"client_credentials\");\n      request.AddParameter(\"client_id\",\"your_client_id\");\n      request.AddParameter(\"client_secret\",\"your_client_secret\");\n      var response = client.Execute(request);\n      Console.WriteLine(response.Content);\n"
                summary: CSharp
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClientCredentials'
  /oauth/clients:
    get:
      tags:
      - Authentication
      summary: Managing OAuth Clients
      description: "<p>To verify incoming API requests, Canoe's APIs use access tokens.</p>\n<p>Canoe API users may <a href=\"#managing-oauth-clients\">create and manage their OAuth Client</a>, and use the <code>Client ID</code> and <code>Client Secret</code> to request an authorization code and access token.</p>\n<p>Canoe API users can also use the <code class=\"prettyprint\">/v1/tokens</code> <a href=\"#password-grant-tokens\">endpoint</a> to manage the access tokens. To authenticate to the <code class=\"prettyprint\">/v1/tokens</code> endpoint, you will need API user credentials. This is one of the few API endpoints where you will need to use your user credentials; most other endpoints are authenticated through access tokens.</p>\n<aside class=\"notice\">\n    Note: An access token issued from Canoe will expire in 24 hours.\n</aside>\n<p>Once you have an access token, you can authenticate to Canoe's API endpoints. Pass the access token in the request header in the format <code class=\"prettyprint\">Authorization: Bearer {token}</code>, where <code class=\"prettyprint\">{token}</code> is your newly created personal access token.</p>\n<p>For example, if your newly created access token is \"eyJ0eXAiOiJKV1QiLCJhbG\", your header should look like \"Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG\"</p>\n<p>If you are using Postman Collection for testing purpose, you could follow the steps here: <a href=\"https://learning.getpostman.com/docs/postman/sending_api_requests/authorization/#bearer-token\" target=\"_blank\"><u>Authorization - Bearer Token</u></a></p>\n<aside class=\"notice\">\n    Note: Sometimes, you want to give API access only to some specific IP addresses. Please contact us to enable that.\n</aside>\n\n<p>Developers building applications that need to interact with Canoe's API need to first register their application by creating a Client account. Typically, this consists of providing the name of their application and a URL that your application can redirect to after users approve their request for authorization. When a Client is created, it will be issued a <code>Client ID</code> and <code>Client Secret</code>. These values will be used when requesting access tokens from your application. </p>\n\n<p>Canoe API users can create and manage their OAuth Clients through the <a href=https://client.canoesoftware.com/api_configuration target=\"_blank\"><u>API Configuration Dashboard</u></a>.</p>"
      operationId: ManageAuthClient
      responses:
        '200':
          description: Success
      security:
      - bearerAuth: []
    servers:
    - url: https://api.canoesoftware.com
      description: Production API
  /oauth/token:
    post:
      tags:
      - Authentication
      summary: Requesting Tokens - Authorization Code
      description: '/oauth/token


        <p>Once a client has been created, you may use the <code>Client ID</code> and <code>Client Secret</code> to request an

        authorization code and access token from your application. First, your application should make a redirect request to

        Canoe''s <code>oauth/authorize</code> route (see examples on the right panel)</p>


        <p>When receiving authorization requests, Canoe will ask users to approve or deny the authorization request. If users approve the request, they will be redirected back to the <code>redirect_uri</code> that was specified by the application that requested access (your application). The <code>redirect_uri</code> must match the <code>redirect</code> URL that was specified when the client was created.</p>

        <p>If the user approves the authorization request, they will be redirected back to the consuming application with the authorization code. The consumer should then issue a <code>POST</code> request to Canoe to request an access token. The request should include the authorization code that was issued by Canoe when the user approved the authorization request. See examples on the right panel and the parameters for the <code>POST</code> request below.</p>'
      operationId: RequestingTokensAuthCodes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: The grant_type parameter must be set to "authorization_code".
                  example: authorization_code
                client_id:
                  type: string
                  description: Your Application's Client ID.
                  example: client-id
                client_secret:
                  type: string
                  description: Your Application's Client Secret.
                  example: your_client_secret
                redirect_uri:
                  type: string
                  description: Your Application's redirect URL. <b>It must match the redirect URL that was specified when the client was created.</b>
                  example: https://your-application.com/callback
                code:
                  type: string
                  description: The authorization code issued by Canoe when the user approved the authorization request.
                  example: code
              required:
              - grant_type
              - client_id
              - client_secret
              - redirect_uri
              - code
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorizationCode'
      x-codeSamples:
      - lang: bash
        label: Bash
        source: "#Please go to the link below to authorize access.\n      https://api.canoesoftware.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code\n\n      #Please copy the 'YOUR_AUTHORIZATION_CODE' in the redirect url(YOUR_REDIRECT_URI?code=YOUR_AUTHORIZATION_CODE) after approving access\n      curl -X POST \"https://api.canoesoftware.com/oauth/token\" \\\n          -H \"Accept: application/json\" \\\n          -H \"X-Requested-With: XMLHttpRequest\" \\\n          -H \"Content-Type: application/x-www-form-urlencoded\" \\\n          -d \"grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\""
      - lang: javascript
        label: JavaScript
        source: "const readline = require('readline');\n      const rl = readline.createInterface({\n          input: process.stdin,\n          output: process.stdout\n      });\n      const client_id = 'client_id';\n      const client_secret = 'client_secret';\n      const redirect_uri = 'https://your-application.com/callback';\n      const url = new URL(\"https://api.canoesoftware.com/oauth/authorize\");\n      let params = {\n          \"clie

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/canoe-intelligence/refs/heads/main/openapi/canoe-intelligence-authentication-api-openapi.yml