REST Connector Authentication

Last updated: October 5, 2026Applies to current supported NIM releases

REST connector guide

Match the API's authentication contract to NIM's connection values, authentication mode, token exchange, and request headers.

Choose the authentication scenario

Start with the API's documentation: determine whether it accepts a reusable key, a username and password, a signed request, or an access token obtained from another endpoint. Authentication proves the caller's identity; API roles, scopes, and consent determine which operations that caller can perform.

Set rest.config.authentication to the mode required by the API, then configure the matching request headers or rest.authOptions. The table lists authentication modes, configuration instructions, and examples. Use the REST Connector JSON Schema to validate the property names and values.

API requirement	rest.config.authentication	Configuration	Example
Username/password or an API key carried as Basic credentials	basic_auth	Configure the system's username and password; use extra headers when required.	BambooHR, HelloID
Existing API key or static bearer token	aeries	Put the vendor's exact header name and token prefix in rest.config.headers.	Aeries, Okta, IncidentIQ
OAuth application credentials exchanged for an access token	client_credentials	Use authOptions.type: "client-credentials", a token URL, and optional scopes or Basic client authentication.	PowerSchool, Ed-Fi
Certificate/private key signs a JWT assertion for a token exchange	certificate	Use authOptions.type: "signed-jwt", JWT claims, and the provider's token request body.	Azure AD / Entra ID, Google Workspace
JWT-specific authentication	jwt	Set authOptions.type: "jwt" and configure JWT, authUrl, and scopes for the provider.	JWT configuration
Login response contains a token, a raw token string, or a vendor-specific token envelope	custom_post_token	Configure the login request, response paths, and resource-request header template.	OpenPath, Tableau, CyberARK PAM
Vendor-specific OAuth grant or explicit refresh-token exchange	custom_post_token	Supply the vendor's grant fields in postData; match form encoding and token parsing.	Zoom, Paycor
Browser authorization and consent before token exchange	authorization_code_grant	Configure loginUrl, authUrl, and scopes, then complete authorization in NIM Studio.	Cisco Webex, D2L Brightspace, GitHub
OAuth resource-owner password grant	password_grant	Set authOptions.type: "password_grant" and configure the token endpoint and grant fields. For a custom token request body, use custom_post_token.	Password-grant configuration; SalesForce and Ceridian Dayforce illustrate the custom-token variant.
HTTP Digest challenge/response	digest	Configure credentials and, when needed, authOptions.type: "digest" and digest options.	Alma
Duo API request signing	duo_auth	Use the dedicated mode and the integration's credentials and API hostname.	Cisco Duo

Keep connection values separate from authentication options

Configure authentication in these locations:

Location	Responsibility
connection.items and the system's Connection tab	Administrator-supplied credentials, tenant identifiers, certificate selection, and additional API-specific inputs.
rest.config.authentication	The NIM authentication mode.
rest.authOptions	How NIM acquires or constructs a token: endpoint, grant, request encoding, claims, response paths, and token header.
rest.config.headers	Headers sent to resource endpoints, including API keys, subscription keys, and tenant/site identifiers.
An operation's authOptions	Endpoint-specific authentication options, such as Google API scopes.

The names are intentionally different: authentication: "client_credentials" pairs with authOptions.type: "client-credentials"; certificate-backed assertions use type: "signed-jwt". Copy the exact schema values, including underscores, hyphens, and capitalization.

Use connection substitutions such as {client_id}, {client_secret}, {user_name}, {password}, and {tenant_id} instead of real credentials in JSON. For signed JWTs, use generated values such as {"name": "clientId"} and {"name": "tenantId"} where a claim or token-request field requires them. Generated-value objects and text substitutions use different syntax; follow the configuration examples below.

For a custom secret field, use a password control:

{
  "name": "api_key",
  "type": "textbox",
  "label": "API key",
  "password": true,
  "order": 10
}

This masks the input in the connection screen; keep secrets out of source control, screenshots, and diagnostic output as well. See Design the connection screen.

The following JSON examples are fragments to merge into a connector, not complete connector definitions. Replace example endpoints and define any additional connection inputs before testing.

Static API keys and Basic credentials

API key or bearer token in a header

Use authentication: "aeries" to send a static API key or bearer token through rest.config.headers. Set the header name and value format required by the API:

"rest": {
  "config": {
    "baseUrl": "https://api.example.com/v1",
    "authentication": "aeries",
    "call_handling": "generic",
    "get": {},
    "headers": { "Authorization": "Bearer {client_secret}" },
    "test_connection": { "url": "/me" }
  }
}

Keep the header spelling and prefix required by the API. Header examples include AERIES-CERT, apikey, X-Authorization, AccessToken, and Tools4everClientSecret. For Okta, use Authorization: SSWS {client_secret}; for IncidentIQ, include both the bearer token and SiteId. Maintain static credentials on the Connection tab when they expire or change.

When an API requires both an API key and a bearer token, configure both headers. The SCIM connector and AWS Identity connector provide examples of x-api-key alongside a bearer header.

Basic authentication and additional keys

For basic_auth, configure the username and password on the Connection tab in the format the vendor requires. An API key can occupy a Basic credential field; it is not necessarily a separate header.

Some APIs require another credential alongside Basic authentication. The UKG Pro connector adds US-Customer-Api-Key; MySchoolBucks adds AppAuthorization. Configure both layers rather than replacing the Basic authentication setting with the additional key.

OAuth client credentials

Use this pattern when an application identifies itself with a client ID and secret, without an interactive user login:

"rest": {
  "config": {
    "baseUrl": "https://api.example.com/v1",
    "authentication": "client_credentials",
    "call_handling": "generic",
    "get": {},
    "test_connection": { "url": "/users" }
  },
  "authOptions": {
    "type": "client-credentials",
    "authUrl": "https://identity.example.com/oauth/token",
    "scopes": ["users.read"],
    "useBasicAuthPost": true
  }
}

Set useBasicAuthPost: true when the token endpoint expects the client ID and secret in a Basic authentication header rather than the token-request body. This authenticates the token request; resource requests use the resulting access token. See Ed-Fi for an example.

grantType defaults to client_credentials. Set the token URL and scopes for the provider. Grant the corresponding application permissions or consent on the provider side.

Certificate-backed and signed JWT exchanges

A signed JWT can authenticate the client during an OAuth exchange or act as the grant assertion. Set authOptions.type: "signed-jwt", then configure the JWT claims and token-request body for the provider. The following examples show Microsoft client assertions and Google service-account assertions.

Microsoft client assertion

For a Microsoft certificate-backed client assertion, set authentication: "certificate" and call_handling: "azure". Configure the token body and JWT claims as follows:

"authOptions": {
  "type": "signed-jwt",
  "authUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "scopes": ["https://graph.microsoft.com/.default"],
  "postData": {
    "client_id": { "name": "clientId" },
    "scope": { "name": "scope" },
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": { "name": "JWT" },
    "grant_type": "client_credentials"
  },
  "JWT": {
    "aud": { "name": "endpoint" },
    "exp": { "name": "oneHour" },
    "iss": { "name": "clientId" },
    "jti": { "name": "guid" },
    "nbf": { "name": "now" },
    "sub": { "name": "clientId" }
  }
}

Select a certificate with its private key in NIM, register the corresponding public certificate with the provider, and grant the required application permissions. Follow Configure Microsoft Entra ID for the wizard or manual setup. Use the correct resource scope for other Microsoft APIs.

For an API that uses a signed assertion with the client-credentials mode, pair authentication: "client_credentials" with authOptions.type: "signed-jwt". See ADP Workforce for an example.

Google service-account assertion

For a Google service-account assertion, set authentication: "certificate" and call_handling: "google". Use the JWT bearer grant in the token body:

"postData": {
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": { "name": "JWT" }
},
"JWT": {
  "iss": { "name": "clientId" },
  "scope": { "name": "scope" },
  "aud": { "name": "endpoint" },
  "exp": { "name": "oneHour" },
  "iat": { "name": "now" },
  "sub": { "name": "tenantId" }
}

Here, sub identifies the delegated subject according to the Google connection setup, rather than following Microsoft's client-ID pattern. See Configure Google Workspace for service-account credentials and domain-wide delegation.

Use authOptions.allowedHosts to restrict which hosts receive the token. Include every API hostname that needs authenticated requests; for example, include sheets.googleapis.com when calling the Google Sheets API.

Use certificate for certificate-backed token assertions. Mutual TLS is a separate transport requirement to address when the target API requires it.

JWT authentication

Set rest.config.authentication to jwt and rest.authOptions.type to jwt. Configure authUrl with the provider's authentication endpoint, scopes with the requested permissions, and JWT with its required claims. Claim values can be literals or generated-value objects, such as "aud": {"name": "endpoint"} and "exp": {"name": "oneHour"}. Configure the signing credentials required by the provider on the Connection tab.

Custom token acquisition

Use custom_post_token when the API requires control over the login request or token-response format:

"rest": {
  "config": {
    "baseUrl": "https://api.example.com/v1",
    "authentication": "custom_post_token",
    "call_handling": "generic",
    "get": {},
    "test_connection": { "url": "/users" }
  },
  "authOptions": {
    "type": "custom_post_token",
    "authUrl": "https://api.example.com/auth/login",
    "postData": { "email": "{user_name}", "password": "{password}" },
    "tokenPath": "data.token",
    "headerName": "Authorization",
    "headerTemplate": "Bearer {token}"
  }
}

Match the request and response

Option	What to configure
authUrl	The login or token endpoint; it can differ from the API base URL.
httpVerb	Login-request HTTP method; defaults to post. postData is ignored for get and delete.
postData	Provider-specific credentials and grant fields; nested JSON is supported in this branch.
postAsForm	Set to true for form-encoded token requests; the default is JSON.
postHeaders	Headers for the token endpoint, such as Verkada's x-api-key.
useBasicAuthPost	Enable Basic authentication for the token request when required, as in JAMF and Zoom.
tokenPath	Response path without a leading $.; NIM adds that prefix. Omit it when the whole response is the token.
expiresPath	Response expiry path. When omitted, the token expires after one hour. Match the provider's token lifetime and returned format.
headerName	Header on subsequent API calls; defaults to Authorization.
headerTemplate	Token format; defaults to Bearer {token}. Use {token} when the vendor expects no prefix.
dataToVariables	Map other response fields into variables for later requests; paths are also prefixed with $..

For example, set tokenPath: "data.token" for OpenPath. For JAMF, use tokenPath: "token" and expiresPath: "expires". Omit tokenPath for a whole-response token, as in CyberARK PAM and Team Dynamix. For Tableau, read credentials.token, send it as X-Tableau-Auth: {token}, and map credentials.site.id to site_id. Vanco ASAP uses the header asap_accesstoken, while Verkada uses x-verkada-auth.

Use postHeaders for the token exchange and rest.config.headers for resource calls. For example, Paycor requires both a bearer token and an Ocp-Apim-Subscription-Key on resource requests. Configure Authorization headers to match the selected authentication flow and avoid conflicting static and acquired tokens.

Vendor grants and refresh tokens

For Zoom, set grant_type: "account_credentials" and account_id in postData, enable form encoding, and use Basic authentication on the token request. For Paycor, set grant_type: "refresh_token" and supply the client credentials, subscription key, and client_refresh_token.

Use custom_post_token for both patterns. When the provider rotates refresh tokens, maintain the connection's refresh credential according to its renewal requirements and test access after rotation.

Existing password-grant integrations

To configure a password-grant integration, set authentication: "password_grant" and authOptions.type: "password_grant". Configure authUrl, grantType, and any required scopes, extraTokenRequestData, or extraParameters. For an API-specific token body, use custom_post_token with grant_type: "password" in postData; Aruba ClearPass, Ceridian Dayforce, and SalesForce provide examples.

RFC 9700, OAuth 2.0 Security Best Current Practice prohibits the resource-owner password credentials grant. For a new OAuth integration, choose a provider-supported application or authorization-code flow. Use password-grant configuration only when maintaining an integration that requires it.

Interactive authorization-code grant

Use this when the provider requires a user to sign in and authorize the application:

"authOptions": {
  "type": "authorization_code_grant",
  "authUrl": "https://identity.example.com/oauth/token",
  "loginUrl": "https://identity.example.com/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scopes}",
  "scopes": ["users.read"]
}

Pair the options with authentication: "authorization_code_grant". Register the callback required by your NIM installation with the provider and complete the login action in NIM Studio. Use {scopes} in loginUrl for scope substitution and connection values for the client ID and redirect URI. See Webex, D2L, and GitHub for examples.

Validate the initial authorization, scheduled access after the access token expires, and recovery after consent or refresh credentials are revoked. Follow RFC 9700 for redirect-URI checks and authorization-code protections, and confirm that your NIM installation meets the provider's requirements, including PKCE when required.

Digest and Duo request signing

HTTP Digest

Set authentication: "digest" and configure the credentials on the Connection tab. Use authOptions to set digest options, as in this example:

"authOptions": {
  "type": "digest",
  "algorithm": "SHA-256",
  "cnonceSize": 32,
  "precomputedHash": false
}

Match the API's challenge and supported algorithm. algorithm defaults to MD5 and accepts MD5, SHA-256, SHA-512-256, SHA-512, and their -sess variants. Use precomputedHash only when the supplied password field already contains the required computed hash. See Alma for a Digest authentication example.

Duo

Set authentication: "duo_auth" and configure the integration credentials and API hostname on the Connection tab. This mode uses signed API requests and does not require a token endpoint or authOptions. Follow Duo's authentication documentation for endpoint requirements and see Cisco Duo for a configuration example. Confirm that the installed NIM version supports the signing requirements of your selected endpoints.

Extend authentication options per operation

Set an operation's authOptions.scopes when it needs API permissions specific to that endpoint. For example, a Google Classroom read operation uses:

"courses_get": {
  "method": "get",
  "authOptions": {
    "scopes": ["https://www.googleapis.com/auth/classroom.courses.readonly"]
  },
  "call": { "mode": "normal", "path": "https://classroom.googleapis.com/v1/courses" }
}

Place authOptions on the operation, alongside method and call, to extend the shared authentication options. Set the authentication mode in rest.config.authentication; there is no separate operation-level authentication property. Authorize each required scope with the provider and test access to each API, such as Directory, Classroom, and Gmail.

See Configure API operations and Configure REST requests for the surrounding configuration.

Validate authentication before scheduling

1. Validate the connector against the current schema, including the required authOptions.type and properties for the selected authentication mode.
2. Configure credentials and run Test Connection against a read-only endpoint that requires the same identity as normal calls. Then collect one representative table from each API or scope group.
3. Inspect the response status and sanitized request details. Check token URL, JSON versus form encoding, token-response path, header name/prefix, tenant, audience, scopes, and provider-side permissions.
4. Repeat access after expiry and after a controlled credential rotation. For certificate assertions, check private-key availability, provider registration, certificate validity, and system time.
5. Test a representative write separately when the connector will provision accounts. Read access alone does not establish write permission.

directToken is deprecated because NIM handles the initial token automatically; omit it from new configurations. Set treat500AsAuthError only for APIs that report authentication failure as HTTP 500.