Digital Toolkit

Troubleshooting

Troubleshooting
Woman looking at computer screen - Photo by Christina Morillo: https://www.pexels.com/photo/black-and-silver-laptop-computer-on-round-brown-wooden-table-1181243/
If you are having issues with the Digital Toolkit, try troubleshooting the issues by stepping through the questions below.

General Tips

Be careful with copying and pasting

In some of our documentation, you may see instances of text like <api_key> or {ACCESS_TOKEN}.

In general, these are meant as “fill in the blank” type examples, where you will need to fill in your own inputs. The brackets (<>, {}, or []) should not be included in your final input.

5xx error codes

In general, if you are receiving an error code in the 5xx range, there is an issue with the server itself.

It’s hard to generally say what the issue is, but usually, it’s best to simply try again later.

Common reasons for a 5xx is maintenance or an intermittent error.

Other troubleshooting

If you’re still having issues, we encourage you to read our documentation for more clarity.

We also have a regularly scheduled technical office hours session where we are able to answer live Q&A from the audience. You can register here.

We also recommend checking out the official tag on Stack Overflow.

Error support

From time to time, users receive errors that they are unable to troubleshoot on their own. With some details, we can help. Please use the template below to create a new Stack Overflow question.

x-request-id: This can be found in your error response

Date: Date and time of request

Client ID: What client ID are you using for your request?

Authentication URL: What URL are you using to authenticate?

Redirect URL: What redirect URL are you specifying?

Reminder
Never share private information, such as secret keys.

Network connectivity

These are general suggestions to diagnose and troubleshoot network connectivity errors on your device.

  • Use a fully public URL on a standard port when serving up content from your web server.
  • Ensure all resources are served using https (without mixing and matching http content).
  • Use a public network and not an internal Wi-Fi connection nor VPN.
  • If using a mobile device, turn off Wi-Fi on the device and use the cellular service (or the reverse).

Signing into JackHenry.Dev

These steps may be helpful to troubleshoot when signing into the JackHenry.Dev developer portal.

Signing up for the first time

If you (or your company) are using Google Workspace (formerly G Suite), then it’s possible that your Google Workspace administrator has denied access to third party apps (e.g., the one we use to offer Sign in with Google to create a developer account).

Please have your Google Workspace administrator review these steps to grant access: https://support.google.com/a/answer/7281227?hl=en

Logging in again after previously signing up

If you have previously signed up and are having trouble logging in again, then you may need to try these steps.

Refresh the browser page

Many issues are resolved by refreshing the browser page and signing in again.

If that does not work, then you may need to force a hard refresh of cached data. The steps to do so depend on the combination of your browser and operating system. These are the keyboard shortcuts for common browsers and operating systems.

Chrome, Firefox, or Edge for Windows: Ctrl+F5 (or Shift+F5 or Ctrl+Shift+R)

Chrome or Firefox for Mac: Shift+Command+R

Safari for Mac: Command+Option+R

Delete cookies

If refreshing the browser page does not work, then you may need to clear the cookies for jackhenry.dev and try signing in again.

JackHenry.Dev configuration options

Updating the primary redirect URI

If you are using the JackHenry.Dev developer portal, make sure that the primary redirect URI is correctly set.

It is important to note that more than one redirect URI can be configured, however only one is designated as the primary redirect URI. Double check your configuration to make sure that the URI you expect is correctly set as the primary redirect URI.

JackHenry.dev Developer Portal External Application Redirect URI

Configuring a plugin

If you are using the JackHenry.Dev developer portal, you are able to configure some aspects of your development plugin.

It is important to press the Save button after making any changes to have your plugin update correctly.

JackHenry.dev Developer Portal Plugin Configuration

Consumer API

If you are having issues with the Consumer API, try troubleshooting the issues by stepping through the questions below.

Is the URL correct?

There are two components to the URL that you may want to check you are using correctly:

  1. Ensure you are using the correct Base URL for the Consumer API.
  2. Ensure that you are specifying the correct Version for the Consumer API.

Is the authorization header valid?

If you see an error code similar to 401 Unauthorized, then you are most likely not properly sending your authorization.

Clients must send their Access Token through the Authorization header when making a request.

A basic cURL example looks something like this:

https://example.com
   -H "Accept: application/json"
   -H "Authorization: Bearer {ACCESS TOKEN}"

See the Authentication (Command Line) quickstart for more details on how to obtain an Access Token for the Consumer API.

If you see an error code similar to 403 Forbidden, this means that you are properly authenticated, but the Access Token does not have the required level of access for the resource you are requesting.

If the request is returning an error related to scopes and claims, your application may not be properly configured to request the data you are trying to access.

  • Scopes can be configured in your request header when authenticating.
  • Claims enable extra data properties in the id_token and responses from the user info endpoint, and must be configured via your external application.

More information about scopes and claims is available in our Authentication Framework docs.

Admin API

If you are having issues with the Admin API, try troubleshooting the issues by stepping through the questions below.

Is the URL correct?

There are two components to the URL that you may want to check you are using correctly:

  1. Ensure you are using the correct Base URL for the Admin API.
  2. Ensure that you are specifying the correct Version for the Admin API.

Many of the endpoints in the Admin API will require an Institution ID. Unless otherwise specified, you should use the Institution ID in UUID format.

Is the authorization header valid?

If you see an error code similar to 401 Unauthorized, then you are most likely not properly sending your authorization.

Clients must send their Access Token through the Authorization header when making a request.

A basic cURL example looks something like this:

https://example.com
   -H "Accept: application/json"
   -H "Authorization: Bearer {ACCESS TOKEN}"

See our Authentication - Client Credentials (Command Line) quickstart for more details on how to obtain an Access Token for the Admin API.

If you see an error code similar to 403 Forbidden, this means that you are properly authenticated, but the Access Token does not have the required level of access for the resource you are requesting.

If you are receiving an HTTP 403 error, it’s possible that the Associated User does not have the appropriate permissions granted for that specific endpoint. See the API Reference for the specific endpoint to find the specific permissions required.

Have a Question?
Have a how-to question? Seeing a weird error? Get help on StackOverflow.
Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.
Last updated Tue Jul 18 2023