Integrations - Quick Guide

  • Updated

This section covers how partners connect external systems to Neostella — integration users, permissions, and webhooks. Along the way, a hands-on activity and several worked API examples tie these concepts together.

 

1. Integration User

Integration users let external systems connect to Neostella securely, without relying on a real person's login. Before an external system can call the Neostella API, it needs its own identity — an integration user — along with the credentials (Client ID and Secret) used to authenticate. 

This is typically the first thing you'll set up before building any integration.

  1. Go to: Control Center → Access → Users, then select the Integration User tab at the top.
  2. View existing integration users, or create a new one.
  3. Specify the scopes the integration user needs.
  4. Save to generate a Client ID and Client Secret.
  5. For an existing user, edit its scopes or generate new credentials as needed.


NOTE: Regenerating credentials immediately invalidates the old Client ID/Secret — anything still using them will stop working.

 

2. Permissions

An integration user has no access to anything until it's added to a permission set — creating the user alone does not grant access. (See Permission Sets in General Platform for general setup details.)

  1. Go to the relevant Permission Set.
  2. Select the Assignee tab.
  3. In the bottom-left section, assign the integration user to the permission set.

 

3. Scopes vs. Permission Sets

Integration users are controlled by two separate mechanisms. Here's what each one does:

Scope

  • What it controls: Which specific resources or endpoints an integration user can reach.
  • Where it applies: Within a single platform area, broken down into smaller pieces. Control Center, for instance, is made up of several distinct resources — Permissions, Groups, Admin, Schema, and more — each with its own scope.
  • Example: A scope can grant an integration user access to the Schema resource in Control Center, without granting access to Permissions or Groups.

Permission Set

  • What it controls: The actions an integration user can take — create, view, edit, delete.
  • Where it applies: Across objects, modules, and contexts, the same way it works for regular users.
  • Example: A permission set can grant an integration user Create and Edit access to the Projects object.

The distinction: scopes define which resources are reachable. Permission sets define what actions are available on them.

 

4. Webhooks

Webhooks allow Neostella to send real-time information to external systems when specific events or actions occur within the platform. Follow the steps below to configure a webhook:
 

  1. Go to: Control Center → Account → Webhooks. This opens the Event Catalog, showing the objects (projects, leads, emails, documents, etc.) and actions (created, updated, deleted) you can trigger a webhook from.
  2. Select the Endpoints tab to manage outbound webhooks.
  3. Add a new webhook by specifying the endpoint URL and the events that should trigger it.
  4. Retrieve the signing secret to validate payloads on the receiving end.
  5. View past delivery attempts for troubleshooting.


 

Note: A new endpoint is enabled immediately upon creation — there's no draft or staged state before it starts firing.

 

5. Get Bearer Token Example

WARNING:The examples in this section use Bruno to send API commands to Neostella, authenticated as an Integration User. You'll need Bruno (or a similar API client) installed to follow along.

This example walks through the Auth section of the API documentation to retrieve a bearer token.

  1. In Bruno, create a new HTTP request.
  2. Set the method to POST and the URL to https://api.neostella.app/v1/oauth2/token.
  3. No authorization is required for this request.
  4. In the Body tab, select raw / JSON, and enter your Client ID and Client Secret:
{
    "client_id": "XXX",
    "client_secret": "XXX",
    "grant_type": "client_credentials"
}
  1. Send the request.

NOTE: A successful request returns a 200 response containing an access_token. Use this token to authorize all future API calls. The response also includes the token's expiration — by default, tokens expire every 60 minutes.

 

6. Get Project List through API Example

The examples in this section use Bruno to send API commands to Neostella, authenticated as an Integration User. You'll need Bruno (or a similar API client) installed to follow along.

This example walks through the "List projects (search, filter, pagination)" section of the API documentation.

  1. First, get an access token as shown in the previous example.
  2. In Bruno, create a new HTTP request.
  3. Set the method to POST and the URL to https://api.neostella.app/v1/projects/list.
  4. Go to the Authorization tab, select Bearer Token as the auth type, and enter the access token.
  5. In the Body tab, enter:
{}
  1. Send the request.

NOTE: A common error is a 403 Not Authorized to Perform response — if you see this, check that the integration user's permissions include access to Projects.

 

7. Upload Document through the API to S3

WARNING: The examples in this section use Bruno to send API commands to Neostella, authenticated as an Integration User. You'll need Bruno (or a similar API client) installed to follow along.

Document creation is a two-step process: first creating the document record, then uploading the file itself to the S3 location returned by that first call.

 

Step 1: Create the Document Record

  1. In Bruno, create a new HTTP request.
  2. Set the method to POST and the URL to https://api.neostella.app/v1/documents.
  3. Go to the Authorization tab, select Bearer Token, and enter the access token.
  4. In the Body tab, enter a request like:
{
  "documents": [
    {
      "description": "Test for partner explanation",
      "external_url": "https://documents.com",
      "file_size": "200 MB",
      "file_type": "docx",
      "instance_kind": "project",
      "is_external": false,
      "is_form": false,
      "name": "Test Doc.docx",
      "projects": ["1558feef-4007-4320-9567-15cfd31aab00"],
      "source": "user",
      "status": "active",
      "tags": []
    }
  ]
}
  1. Send the request. A successful response includes a post_url object, similar to:
{
  "documents": [
    {
      "id": "...",
      "name": "Test Doc.docx",
      "post_url": {
        "url": "https://<bucket>.s3.amazonaws.com/",
        "fields": {
          "AWSAccessKeyId": "...",
          "key": "...",
          "policy": "...",
          "signature": "...",
          "x-amz-security-token": "..."
        }
      }
    }
  ]
}


NOTE: The values inside post_url.fields are required for the next step, and are generated specifically for this upload — they can't be reused for a different document.

 

Step 2: Upload the File to S3

  1. In Bruno, create a new HTTP request.
  2. Set the method to POST and the URL to the value returned in post_url.url (for example, https://neo-tenant-0fbf5c9d-2276-4d9f-b32c-ee64ee325991.s3.amazonaws.com/).
  3. Set the body type to multipart/form-data and add the following fields:
Form Key Type Value
AWSAccessKeyId Text post_url.fields.AWSAccessKeyId
key Text post_url.fields.key
policy Text post_url.fields.policy
signature Text post_url.fields.signature
x-amz-security-token Text post_url.fields.x-amz-security-token
file File The document you want to upload

NOTE: All text field values must be copied directly from the response of the first API call — they're generated specifically for that upload request and won't work for a different one.

 

Step 3: Verify the Upload

Once the upload completes successfully, navigate to the corresponding record in the Neostella UI and confirm the document was created and is available as expected.

 

 8. How to use: Simple Integration

This section brings together many of the concepts covered earlier in this guide to show how they combine into a real integration. We'll walk through a Quick Guide of what's needed within Neostella to support an integration end to end.

The guide in this section uses Bruno to send API commands to Neostella, authenticated as an Integration User. You'll need Bruno (or a similar API client) installed to follow along.

The following json text is needed for a step inside Bruno:

json

{

  "fields": {

    "portal_url": "https://clientportal.example.com/cases/98765"

  }
}

 

In this scenario, an external client portal needs to stay in sync with new Projects (Cases) created in Neostella. Each time a Project is created, Neostella notifies the portal via webhook. The portal then calls back into Neostella to record its own URL for that case, so staff can jump straight to it in the portal from within Neostella.

 

Follow this tutorial to apply what you learned in this Quick Integration Guide:

 

82 STEPS

1. The first step is to open Neostella and enter the Control Center.

Navigate to Schema and click it.

2. Next, click on Data.

3. Look for the Project object and select it.

4. The following step is to create a new Field.

5. Then add a Name, for this guide we will use Portal URL.

6. Make sure the field's API name is portal_url, since it's referenced in later steps.

7. Click SAVE

8. Next, go to the DISPLAY tab

9. Now we will update the relevant Form to include the Portal URL field, so it's visible in the UI once populated.

10. In the Form editor, look for the Portal URL field, then Click it or Drag it.

11. This will to add the Field to the Form.

12. Click SAVE

13. Now we need to go back to: Control Center.

14. Look for Account.

15. Then click on Webhooks

16. After that, go to Endpoints

17. Click Add Endpoint

18. Set the Endpoint to the URL that should receive the event — for this example the following is used: https://clientportal.example.com

This is where you'd enter your actual client portal endpoint.

19. Search for the Projects Created event.

20. Click the event.

21. And finish the step by clicking Create

22. Now you have configured the Endpoint.

23. Now we must create a Project.

24. Navigate to Cases

25. And create a new PROJECT

26. Enter the required information to create the Project.

27. Click SAVE

28. Now enter the New Project.

29. Confirm the Portal URL field is empty — this is expected, since nothing has updated it yet.

30. The following step is going to Bruno

31. Here we have the Access Token obtained in previous steps of the Integration Quick Guide.

This token is required to complete this guide.

32. Create a new HTTP request.

33. Set the method to PATCH

34.

35. Enter the following URL: https://api.neostella.app/v1/projects/{project_id}

36. Press Meta+V

37. Now replace the: {project_id} with the ID of the Project you just created.

To obtain it, go to Neostella.

38. Click here

39. Open the New Project and look for the URL.

Here you can see the Project ID.

40. Select the ID and copy it.

41. Now go back to Bruno

42. And paste the Project ID in the URL.

43. This is the URL that allows access to the Project information.

44. Now go to Authorization.

45. Click the configuration form options.

46. And select Bearer Token

47. Now go to the previously obtained Access Token.

48. Select and copy the Access Token.

All the information between "".

49. Go back to the new Request

50. And paste the Token here.

51. Now navigate to the Body Tab.

52. Click the configuration form options.

53. And select JSON.

54. Now paste the json on included on the Help Center Article.

55. Here is how the Body should look:

56. Click Send

57. Success

58. Now go back to Neostella.

59. Enter the created Project and Reload the page.

60. The Portal URL field will be updated.

61. To verify via the API as well, go back to Bruno.

62. Create a new HTTP request.

63. Configure the method to GET

64.

65. And the URL to https://api.neostella.app/v1/projects/{project_id}?fields=portal_url, using the same Project ID.

66. Go to the previous request.

67. And select the Project ID.

68. Copy the ID.

69. Go back to the new request.

70. And replace it in the URL.

71.

72.

73. Then, go to Authentication.

74. Click the configuration form options.

75. And select the Bearer Token.

76. Go back to the previously obtained access token.

77. Select and copy the Access Token.

All the information between "".

78. Again, go back to the New Request.

79. And paste the Access Token here.

80. Finally click Send.

81. Confirm the portal_url field appears in the response with the value that was set before.

82. That's it. You're done.

https://www.iorad.com/player/2765574/How-to-use--Simple-Integration