Configure your endpoint request

To configure your endpoint definition, you must create a new record in the Endpoint Definitions application, then:

  • Select the type of endpoint, endpoint location, request authentication type, and request time out options. Learn more in Endpoint general configuration.
  • Configure the headers, query parameters, and payload that are sent to an external REST API system as part of an endpoint request. Select whether your request is a File or JSON request type. Learn more in Endpoint request configuration. 
  • Configure your response set and response codes. Learn more in Endpoint response configuration. 

Initiate your endpoint request

Once your endpoint definition is configured, you must use logic blocks to configure the criteria for when it is initiated. For example, you could initiate the endpoint request when a user selects a form action or field action. In the Logic Block Builder, configure a transactional logic block which calls the Call External Endpoint action. Learn more in Call External Endpoint action 

Review errors

Use the Endpoint Log Inquiry application to review log records which indicate if an endpoint request was successful or failed. Learn more in Endpoint Log Inquiry application.

Endpoint general configuration

Configure the type of endpoint, HTTP method, authentication, and timeout options on the General page of the Endpoint Definitions application. 

Endpoint Definitions

To configure your endpoint request, in the Endpoint Definitions application, on the General page, you must:

  • In the Type field, select your endpoint type. Options include: 
    • Method—Calls in a logic block and performs an action relevant to the business process. 
      • This endpoint type can specify a Token Creation endpoint as its Authentication Type. When this configuration option is selected, the Token Creation endpoint is automatically called first by the logic block.
    • Token Creation—Establishes a session with an external system. A request to the token endpoint is used to exchange an authorization code for an access token. Multiple endpoints can have the same token creation endpoint as their Authentication Type. For example, if you need to call a series of endpoints in a logic block, then they all re-use the same token.
    • Token Release—Releases a session with an external system. 
    • AI—Connects AI model versions to the host that runs the model, such as Anthropic or OpenAI. Learn more in Connect AI model versions to a host.
  • Select the the HTTP Method. This indicates what type of action the API request is performing, such as GET, POST, or PUT. 
  • Select the Authentication Type. The type of authentication needed is dictated by the server you are requesting information from. This can be one, or many, types of authentication. Each authentication type requires different configuration steps. Learn more in Endpoint authentication options. 
  • Optionally, select the length of time before a request times out, the number of times a request is attempted, and how long to wait before attempting another request attempt.
  • Optionally, select the Enable Logging checkbox to enable endpoint logging. When selected, a log is created for every interaction in the endpoint. When cleared, logs are only created for failed requests. 
  • Select whether the endpoint only logs failed attempts, or if it logs every request attempt, response, and failure. View log records in the Endpoint Log Inquiry application. 

Once you have configured the General page of your definition, you must define your Request and Response information. Then, you'll configure a transactional logic block which uses the Call External Endpoint action to initiate your endpoint request. Learn more in: 


Endpoint authentication options

Nextworld supports multiple authentication types for endpoint request calls, including OAuth 2.0, JSON Web Tokens, and secrets. The type of authentication used in your endpoint request is dictated by the server you are requesting information from. This can be one, or many, types of authentication. 

Select your authentication type in the Authentication Type field, on the General Configuration page of your Endpoint Definitions application record. Each authentication type has different requirements, as seen in the subheadings below. 

No Auth

The endpoint request does not require authentication. No further configuration is required. 

Basic Auth

Requires a verified username and password, known as a secret, to access a data resource. Secrets are configured as Key-Value pairs in the Endpoint Secret Setup application. Navigate to the application from the Navigation Menu or select the Configure Secret field action. Learn more in Endpoint Secret Setup application.

You can optionally configure a logic block to automatically update the endpoint secret at set intervals. Learn more in Automatically update endpoint secrets.

Token

Requires another configured endpoint to generate a token that is then used to authenticate this endpoint definition. Reference the endpoint definition that retrieves the token. 

OAuth 2.0

Requires authentication through a third-party website to grant access. The authentication provides an access token which is used for subsequent requests from our platform to the responding server. OAuth grant types include:

  • Authorization Code—Retrieves an access token once users sign into the external system. Nextworld exchanges an authorization code for the access token which is stored in the OAuth record. 
  • Refresh Token—Retrieves only a refresh token. 
  • Client Credentials—The client authenticates using a signed JWT client assertion defined in the Endpoint JWT Setup application. Supports both symmetric and asymmetric signing.
    • Client Secret—The client ID and secret are sent to the token endpoint in exchange for an access token. You can optionally configure a logic block to automatically update the secret at set intervals. Learn more in Automatically update endpoint secrets.
    • JWT Assertion—The client authenticates using a JWT client assertion defined in the Endpoint JWT Setup application. 

OAuth is configured in the OAuth Setup application. Navigate to the application from the Navigation Menu or select the Configure OAuth field action. Learn more in OAuth Setup application.

JSON Web Token

Requires a JSON Web Token be sent to our platform from the responding server to authenticate subsequent requests from our platform. JSON web tokens are configured in the JWT Setup application. Learn more in Endpoint JWT Setup application.

SSO

Retrieves a token from the URL defined for the chosen third party. SSO is configured in the Single Sign On application step of the Tenant Environment Setup application. Learn more in Single Sign On application step and Single Sign On configuration.

Endpoint JWT Setup application

Use the Endpoint JWT Setup application to configure JSON Web Tokens to authenticate your endpoint requests. 

JSON Web Tokens contain claims which are relevant for your request. Any number of claims can be required to give context for your token. The server which our endpoint requests information from provides the values needed to configure the JSON Web Token, which in turn provides authorizations for us to access the server information. 

Access the Endpoint JWT Setup application from the Navigation Menu, or with the Configure JWT field action in the Endpoint Definitions application. The field action is only visible if the Authentication Type selected in the Endpoint Definition record is JSON Web Token. 

JWT Setup records can be generated in the platform with a symmetric or asymmetric algorithm, or generated externally and retrieved with a logic block.

Symmetric

Define the secret, algorithm, and key-value pairs you want included in the JWT request. 

Asymmetric

Define a private key and algorithm to sign JWT requests using asymmetric (public-key) cryptography. Asymmetric signing is required by third-party APIs and identity providers that use the OAuth 2.0 private_key_jwt client credential flow, where a signed client assertion replaces a shared secret.

Import your private key in PEM format and select the JWT Type of Asymmetric. If your private key is passphrase-encrypted, enter the passphrase in the Passphrase (Optional) field. The passphrase is only used during import and is cleared on save. The platform supports the following algorithm families:

  • RSA—Select RS256, RS384, RS512, PS256, PS384, or PS512. Defaults to RS256 if not specified.
  • EC—Select ES256, ES384, or ES512. The algorithm is derived automatically from the key on save.
  • EdDSA—Select Ed25519 or Ed448. The algorithm is derived automatically from the key on save.

The platform does not generate asymmetric key pairs. Generate your key pair externally using an external key management system or OpenSSL, then import the private key.

Logic block 

Provide the name of the logic block which calls the external endpoint to retrieve the JWT, as well as the output of that logic block which will contain the complete JWT. The output must be of type Text. 

Learn more about endpoint configuration in the Outbound endpoint configuration overview topic. 

OAuth Setup application

Use the OAuth Setup application to configure OAuth 2.0 protocols to authenticate your endpoint requests. 

OAuth authorizations enable a third-party application to access an HTTP server on our behalf by initiating an authentication interaction between our platform and the server, or by obtaining access itself. OAuth separates the client from the server whose information it is requesting. The client, in this case Nextworld, is issued an access token by the third-party application that indicates the scope of access and allotted time to access the servers information. 

Access the OAuth Setup application from the Navigation Menu, or from the Configure OAuth field action in the Endpoint Definitions application. Fill in the required fields with information you receive from the server's endpoint documentation, such as the:

  • Grant Type—Specifies how the client authenticates to the authorization server when requesting an access token. 
    • For Client Credentials, you must select an Authentication Type. Options include:
      • Client Secret—The client ID and secret are sent to the token endpoint in exchange for an access token.
      • JWT Assertion—The client authenticates using a JWT client assertion defined in the Endpoint JWT Setup application. 

Once the OAuth information has been configured, you must add an entry into the Headers subtable on the Request page. Learn more in Endpoint request configuration topic. 

Endpoint Secret Setup application

Use the Endpoint Secret Setup application to configure secrets used for basic authorization in endpoint definitions. Once saved, the value of a secret cannot be seen, but the decrypted value is available to endpoint definitions during the REST invocation. 

Secrets are the credentials that authorize you to access an endpoint. The Key acts like a username, and the Secret is the password. Using an endpoint secret for authentication requires someone to know the values of the specific Key and Secret combination in order to request data from the resource.

Endpoint definitions which are permitted access to the secret must be entered in the Allowed Endpoints subtable. Once added, you can reference the secret in the endpoint definition. This allows both Nextworld and Nextworld customers the ability to create endpoint secrets and still have complete control over access to those secrets.

Access the Endpoint Secret Setup application from the Navigation Menu, or from the Configure Secret field action in the Endpoint Definitions application. Learn more about endpoint configuration in the Outbound endpoint configuration overview topic. 

Secrets in production environments

Secret setup records migrate with the Key and Allowed Endpoints subtable values, but the value of a Secret is not included. 

To add a secret in production environments, you must either customize the secret setup record, or use an environment override definition. Environment overrides allow you to change the value of a previously configured field while in a specific environment. This allows you to add the appropriate value into the Secret field for your production environment. 

Learn more in the  Environment Override Definitions application and  Environment override configuration topics. 

Automatically update endpoint secrets

Configure your endpoint to automatically update its secret with the Job Scheduler and Logic Block Builder applications. 

Endpoint secrets are part of certain request authorization types within Endpoint Definitions, such as:

Learn more about endpoint definition configuration in Endpoint general configuration. 

By default, once a secret has been configured it can only be updated manually within the record. To automate this process and have it occur on a scheduled basis, you can:

  • Build a Background Task logic block that uses the Call External Endpoint action to retrieve a new secret or token.  
  • Use the Update Secret action in your logic block to specify which record containing a secret should be updated. 
  • Use the Job Scheduler application to schedule the frequency in which you want the logic block to run. 

Update Secret action

Use the Update Secret action to update a secret stored in the Endpoint Secret Setup or OAuth Setup application. 

Select the type of secret and record which you want to update. Options include:

  • Endpoint Secret—Updates a secret in an Endpoint Secret Setup record.
  • OAuth Client Secret—Updates a secret in a Endpoint JWT Setup record. 

The logic block action automatically registers whether the secret is a Key Value or JWT secret and prompts you for the required information.   

Use cases

This feature can be used with scheduled jobs to automatically update secrets at scheduled intervals. Learn more in Automatically update endpoint secrets. 

Endpoint request configuration

Configure the headers, query parameters, and payload that are sent to an external server's API as part of an endpoint request on the Request page of the Endpoint Definitions application.

Request

In the Endpoint Definitions application, on the Request page, there are several configuration options for different kinds of endpoint requests, such as:

  • In the Request Mapping Table field, select atable which holds the values you want to map into the request. The calling logic block populates a temporary version of that table with a single record before it calls the endpoint. 
  • In the Request Type field, select the type of body you want sent in the endpoint request. Options include: 
    • JSON—Maps records into a streaming JSON body, or builds JSON in a logic block. Defaults to this option if no type is selected. 
    • File—Attachments are sourced from an attachment source record added to the Call External Endpoint action in your logic block record. Select either BINARY or MULTIPART in the File Request Body Type field to control the structure of your file content. Use the Attachment Name Mapping Field field if you want to specify a single, specific attachment from the source record to be uploaded. 
  • Under JSON Payload Map, map any values from the request table that you want included in the request payload. You can use the visual data mapper, or turn off the toggle to access the subtable. 
  • In the Sample Request Payload field, you must create a JSON template for the request payload. JSON template payloads can be sourced from Endpoint Documentation accessible from the Sidebar menu under Integrations. You must navigate to a dashboard page before opening the menu to see the Integrations section.. Mappings done in the JSON Payload Map subtable are validated. 
  • In the Headers subtable, you can specify header parameters that are part of the request. 
    • OAuth authentications configured in the OAuth Setup application must have an entry added into the Headers subtable. In the Key field, enter Authorization, in the Mapping Type field, enter Bearer Token, and in the Value field, enter N/A. 
  • In the Query Parameters subtable, you can include additional parameters that are appended to the URL address. 

For information about endpoint configuration, see the Outbound endpoint configuration overview topic.

Endpoint response configuration

Configure your response set and response codes on the Response page of the Endpoint Definitions application. 

Response

After a request is made to the external server's API, the API sends a response. You must configure how you want the response to be handled. In your endpoint definition, on the Response page, you must: 

  • In the Response Set field, enter an existing response set definition, or define a new one. The response set interprets the server's responses. To configure a new response set:
    • In the Response Mapping Table field, define where to map the data returned from the endpoint call. This table is populated with one or more records depending on the shape of the response, and those records become available in the logic block after calling the endpoint. Learn more in Call External Endpoint action.
    • In the Endpoint Response Codes subtable, configure which HTTP response codes you want handled in the endpoint. Values can be entered as exact matches to the HTTP response code, such as 200, 401, or 402, or they can be entered to match a range of HTTP response codes. To match a range of HTTP response codes, the value must begin with at least one digit followed by one or more x characters. For example, 5xx matches all 500 series HTTP response codes. 40x matches all HTTP response codes between 400 and 409.
  • Select the Manage Response Code form action to further define your response codes' behavior. Open the detail view of the response code records to refine the configuration, such as:
    • The Response Type for your response code. Responses can be of type JSON or File, depending on the value of the Content-Type in the endpoint response. That content-type must match the response type defined here for the endpoint to succeed. Responses can be of type JSON or File (PD.
    • The Authentication Failure checkbox enables the system to initialize an authentication retry or refresh of a token creation endpoint if the response code represents an authorization failure, such as a 401 code. 
    • The Retry checkbox enables the system to retry the request if warranted, such as a 429 code. Additional parameters are defined in the Retry delay (ms) and  Max Attempts fields in the endpoint definition. 
    • For response types of JSON, describe the data you want mapped from the endpoint response to the Response Mapping Table. If the response type is File, no further configuration is needed. 
    • Optionally, create a JSON template for the response. The values entered in the JSON template populates the Example Path Values field in the JSON Payload Map subtable. This template is not used during the endpoint execution.

Auto-authentication refresh after failure

To ensure the system automatically refreshes a token creation after an authentication failure returns a 401 or similar response code, you must:

Navigate to the Endpoint Definitions application and open the record for your endpoint. 

  • On the Response page, select the Configure Response Codes field action. 
  • Ensure an error code is configured against the code which is applicable to your authentication failure, and the Authentication Failure checkbox is selected.  

For information about endpoint configuration, see the Outbound endpoint configuration overview topic.

Call External Endpoint action

Use the Call External Endpoint action to initiate a previously configured endpoint definition. 

The endpoint definition describes the external endpoint to be called, how to construct the request, and how to interpret the response(s). Learn more in the Outbound endpoint configuration overview topic.

In the Logic Block Builder, select the action. In the Detail panels for the action, you must:

  • Enter the name of the definition in the Select an External Endpoint field. 
  • Select your source type in the Source Type field. The available types are:
    • Temp Table—Use when you have passed records into a temp table in your logic block. The records from the temp table are then passed to the endpoint in the request body. Temp tables are limited to 15,000 records. If your requests contains more than 15,000 records, you must use the Table source type. 
    • Table—Use to configure filters that specify which records from the Request Mapping Table in the endpoint definition should be passed in the request body to the endpoint. 
    • Logic Block Signature Mapping—Use when the table the logic block is built over is the Request Mapping Table from the endpoint definition. 
    • JSON—Use when you want to pass JSON objects and variables to external call requests. You must configure the JSON Object/Array in the Set Values action, then reference it here. Learn more in  JSON manipulation in logic blocks.
  • Name your Response DSN. This name can be referenced by other logic block actions that need to query the data provided by the endpoint response.

If your endpoint definition has a response set of type File, you must specify which record in your source table should receive the file attachment. Expand the Add Attachment section to select the record. 

Connect AI model versions to a host

Create an Endpoint Definition with the type AI - AI Host to store the URL and secret for an AI host, so any number of AI model versions can use the same connection.

An AI Host endpoint stores the connection details for one AI host, including its URL and the secret the platform uses to authenticate with it. AI model versions reference an AI Host endpoint, so you can add more models to a host without re-entering its connection details.

AI Host endpoints support Anthropic, OpenAI, and Amazon Bedrock.

Create an AI Host endpoint

To create an AI Host endpoint, in the Endpoint Definitions application, select AI in the Type field, then specify the following:

  • Name—A name that identifies the host. You select this name when you configure a model version.
  • URL—The full address of the endpoint that receives requests, including the path. The URL must match the API style you select in the model version.
  • Authentication Secret—The name of the endpoint secret that holds the API key the platform uses to authenticate with the host. An API key is required for Anthropic and OpenAI. Leave this field empty for Amazon Bedrock, which uses Nextworld's AWS credentials.

The HTTP method is always POST, so you don't need to select one.

Set up authentication for an AI host

AI hosts that use an API key, such as Anthropic or OpenAI, authenticate with a key stored in an endpoint secret. In the Endpoint Secret Setup application, you must:

  • Enter your API key in the secret's value field. Leave the key field empty.
  • Add the name of your AI Host endpoint to the secret's Allowed Endpoints subtable.
  • Enter the secret's name in the Authentication Secret field on the AI Host endpoint.

You don't need to specify a header name. The platform sends the key in the format the provider requires.

Use an AI Host endpoint in a model version

After you create an AI Host endpoint, select it in the AI Host field of an AI Model Version Setup record, select the API Style the host supports, and enter the model name as the provider identifies it. Learn more in AI Model Version Setup application.