Skip to main content

​
Authorization

Base URL 
https://actionkit.useparagon.com/projects/[Project ID]

https://worker-actionkit.[On-Prem Base URL]/projects/[Project ID]
Authentication To authenticate to ActionKit API, present a Bearer token with the Paragon User Token (a JWT): 
Authorization: Bearer [Paragon User Token]
This is the same token that you used to call .authenticate with the Paragon SDK. See examples in Installing the SDK.

​
Pagination

Many list and search actions in ActionKit accept a paginationParameters object as part of the request parameters. When the result set exceeds a single page, the response includes a pageCursor (or equivalent token) that you pass in the next request to retrieve the following page. A typical pagination flow looks like this:
  1. Call an action without any pagination parameters to get the first page.
  2. Check the response for a pagination cursor or token (e.g. nextPageCursor).
  3. If a cursor is present, call the action again with the cursor in paginationParameters.
  4. Repeat until no cursor is returned.
Example: Paginating Asana projects
// First request: no pagination parameters
const firstPage = await fetch(
  `https://actionkit.useparagon.com/projects/${projectId}/actions`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "ASANA_GET_PROJECTS",
      parameters: {},
    }),
  }
);

const firstResult = await firstPage.json();
// Use firstResult.pageCursor for the next request

// Subsequent request: pass the page cursor
const nextPage = await fetch(
  `https://actionkit.useparagon.com/projects/${projectId}/actions`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "ASANA_GET_PROJECTS",
      parameters: {
        paginationParameters: {
          pageCursor: firstResult.pageCursor,
        },
      },
    }),
  }
);
Paragon standardizes vendor-specific pagination mechanics into a few patterns:
Parameter typeDescriptionFieldsExample integrations
Cursor-basedReceive nextPageCursor or nextPageToken and pass that field to paginationParameters in the next call.pageCursor or pageTokenAsana, Confluence, Slack
Offset-basedCount the number of records received in a page and add it to a running offset parameter passed to paginationParameters in the next call.offset or skipMailchimp, Sage Intacct, Zoho CRM
Page numberFor each page, add 1 to a running pageOffset parameter passed to paginationParameters in the next call.page, pageNo, pageNumber, or pageOffsetDropbox Sign, ServiceNow, Xero
You can find the specific pagination parameters available for each action in the Actions Reference. Actions that support pagination include paginationParameters in their input schema.

​
File Uploads

Actions that accept a file input to upload a file to an integration (for example, Google Drive: Save File and Box: Save File) will need to be encoded as part of the JSON payload provided when the Action is run.
  1. Hex-encode the file With the file contents you want to upload, hex-encode of the bytes file that you intend to upload.
  2. Construct a File object A File object is a JSON object that represents a File to upload. You must provide three standard fields:
    File object
    {
    "dataType": "FILE", // Always set to "FILE"
    "mimeType": "text/plain", // Set to the file's known MIME type
    "data": "..." // Use the hex-encoded file data
}

​
Examples

Here are some end-to-end examples of uploading a file with ActionKit in a few different client languages: 
import fs from 'node:fs';
const filePath = './report.pdf';
const fileBuffer = fs.readFileSync(filePath);

const body = {
    action: "GOOGLE_DRIVE_SAVE_FILE",
    parameters: {
        filename: "report.pdf",
        file: {
            mimeType: "application/pdf",
            dataType: "FILE",
            data: fileBuffer.toString('hex'),
        },
    },
};

const res = await fetch(
    `https://actionkit.useparagon.com/projects/${PROJECT_ID}/actions`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${PARAGON_USER_TOKEN}`,
        },
        body: JSON.stringify(body),
    },
);

​
Limitations

ActionKit limits incoming request body payloads to 10 MB. Because of the required hex encoding, uploaded files are effectively limited to 5 MB. For larger file sizes, use the Proxy API to upload to the integration directly.

​
Using Multi-Account Authorization

Multi-Account Authorization is a set of SDK options that enables you to connect multiple accounts of the same integration type for a Connected User. You can use Multi-Account Authorization with ActionKit by specifying a credential with a header of X-Paragon-Credential.
REST API
POST https://actionkit.useparagon.com/projects/<Project ID>/actions

Authorization: Bearer <Paragon User Token>
X-Paragon-Credential: <Credential ID>

// Body
{
    "action": "SLACK_SEND_MESSAGE",
    "parameters": {
        "channel": "#general",
        "message": "Hello world!"
    }
}