API Release Notes - Paragon Documentation

2025-07

Scheduled for release July 7, 2025

Updates to GET /sdk/integrations and Proxy API

To improve the ergonomics of the API, we are introducing a few changes to the GET /projects/:projectId/sdk/integrations and Proxy API endpoints for Custom Integrations.We are also removing some unnecessary fields from the response of the GET /projects/:projectId/sdk/integrations endpoint to improve performance. Please review these changes to ensure that your application is not using any of the fields scheduled for removal.Affected endpoints:

GET /projects/:projectId/sdk/integrations
Proxy API

Breaking changes:

In GET /projects/:projectId/sdk/integrations, the type field of Custom Integrations will now be the full slug that is used in paragon.connect() calls.

Show Example

{
    "id": "77210f70-4f20-4eac-bded-825732b229c3",
    "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
    "customIntegrationId": "d8fe6169-8119-4cb0-a7a9-c2b18aff2c07",
    "name": "Example",
-   "type": "custom",
+   "type": "custom.example",
    "isActive": true,
    "configs": [...],
    "workflows": [...],
    "customIntegration": {
        "id": "d8fe6169-8119-4cb0-a7a9-c2b18aff2c07",
        "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
        "name": "Example",
        "isPublished": true,
        "slug": "custom.example"
    },
    "hasCredential": true,
    "connectedUserLimitOnDevCred": 0,
    "connectedUserLimitReached": false,
    "brandColor": "#000000",
    "needPreOauthInputs": false,
    "authenticationType": "oauth",
    "sdkIntegrationConfig": null
}

In GET /projects/:projectId/sdk/integrations, some unnecessary fields are being removed from Integrations:

To optimize the performance of this endpoint, some fields of Integrations are being removed. Please ensure that the following fields are not in use by your application:
- integration.dateCreated
- integration.dateUpdated
- integration.resourceId
- integration.configs[].dateCreated
- integration.configs[].dateUpdated
- integration.configs[].integrationId
- integration.workflows[].dateCreated
- integration.workflows[].dateUpdated
- integration.workflows[].teamId
- integration.workflows[].isOnboardingWorkflow
- integration.workflows[].workflowVersion
- integration.customIntegration.dateCreated
- integration.customIntegration.dateUpdated
- integration.customIntegration.projectId
- integration.customIntegration.oauthScopes
- integration.customIntegration.oauthIncludeClientAuthorizationHeader
- integration.customIntegration.usePKCEInCodeExchange
- integration.customIntegration.apiBaseUrl
- integration.customIntegration.testEndpointPath
- integration.customIntegration.isTestEndpointVerified
- integration.customIntegration.apiAuthorization
- integration.customIntegration.userProfileConfig

Show Example

{
    "id": "f02dba2f-d149-4664-958d-138d546d987b",
-   "dateCreated": "2023-10-23T17:03:16.211Z",
-   "dateUpdated": "2023-10-23T17:03:16.211Z",
    "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
    "customIntegrationId": "208d5d99-bbb4-4147-b991-83e220da192c",
-   "resourceId": null,
    "type": "custom.spotify",
    "isActive": false,
    "configs": [
        {
            "id": "70c9c3f6-f68c-4e06-921e-0ee678bc6a9f",
-           "dateCreated": "2023-10-23T17:03:16.211Z",
-           "dateUpdated": "2023-10-23T17:03:16.211Z",
-           "integrationId": "f02dba2f-d149-4664-958d-138d546d987b",
            "values": {
                "accentColor": "#000000",
                "description": "play music",
                "workflowMeta": {}
            }
        }
    ],
    "workflows": [
        {
            "id": "0d6660ac-2396-4442-98a3-4321fa6ce42b",
-           "dateCreated": "2024-06-04T13:16:32.660Z",
-           "dateUpdated": "2024-06-04T13:17:03.374Z",
            "description": "Example Workflow",
            "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
-           "teamId": "72c5150b-6bfa-4972-9845-1350f3ee18bc",
-           "isOnboardingWorkflow": false,
            "integrationId": "b62baf56-5030-4105-9c78-dbf307e1ee94",
-           "workflowVersion": 1,
            "steps": []
        }
    ],
    "customIntegration": {
        "id": "208d5d99-bbb4-4147-b991-83e220da192c",
-       "dateCreated": "2023-10-23T17:03:16.211Z",
-       "dateUpdated": "2023-10-23T17:03:16.211Z",
-       "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
        "name": "Spotify",
        "authenticationType": "oauth",
        "inputFields": [],
        "oauthAuthorizationUrl": { "type": "TOKENIZED", "parts": [{ "type": "VALUE", "value": "https://accounts.spotify.com/authorize", "dataType": "STRING" }], "dataType": "STRING" },
        "oauthAccessTokenUrl": { "type": "TOKENIZED", "parts": [{ "type": "VALUE", "value": "https://accounts.spotify.com/api/token", "dataType": "STRING" }], "dataType": "STRING" },
-       "oauthScopes": "user-read-private",
-       "oauthIncludeClientAuthorizationHeader": true,
-       "usePKCEInCodeExchange": false,
-       "apiBaseUrl": { "type": "TOKENIZED", "parts": [ { "type": "VALUE", "value": "https://api.spotify.com/v1", "dataType": "STRING" } ], "dataType": "STRING" },
-       "testEndpointPath": { "type": "TOKENIZED", "parts": [], "dataType": "STRING" },
-       "isTestEndpointVerified": false,
-       "apiAuthorization": { "type": "bearer", "token": { "type": "TOKENIZED", "parts": [ { "type": "CONNECT_CREDENTIAL_FIELD", "fieldType": "OAUTH_ACCESS_TOKEN" } ] } },
        "isPublished": true,
-       "userProfileConfig": {},
        "slug": "custom.spotify"
    },
    "hasCredential": true,
    "connectedUserLimitOnDevCred": 0,
    "connectedUserLimitReached": false,
    "name": "Spotify",
    "brandColor": "#000000",
    "needPreOauthInputs": false,
    "authenticationType": "oauth",
    "sdkIntegrationConfig": null
}

Other non-breaking changes:

Proxy API now supports using the custom.name format when sending Proxy requests for Custom Integrations
- Instead of passing in a customIntegrationId, you will now be able to pass in custom.name (the same slug used for paragon.connect) directly to the Proxy API.
- Example:
  - https://proxy.useparagon.com/projects/:projectId/sdk/proxy/custom/:customIntegrationId/:path + https://proxy.useparagon.com/projects/:projectId/sdk/proxy/custom.integrationName/:path

What do I need to do?

Verify that your use of integrations.type for Custom Integrations does not rely on the value being exactly "custom". The new type field will include the full slug value, e.g. custom.integrationName.
Verify that you are not using any of the fields scheduled for removal from the API.

When are these changes being released?

These changes will be released on July 7, 2025.

​Updates to GET /sdk/integrations and Proxy API

​What do I need to do?

​When are these changes being released?

Updates to GET /sdk/integrations and Proxy API

What do I need to do?

When are these changes being released?