Technical Reference for API Gateway

First published on: 02/21/2024/8:44 pm

This reference provides technical details about Saltbox API Gateway. For tutorials or walkthroughs, see Saltbox API Gateway Overview.

API Gateway Key Management

Managing API Gateway keys video: https://help.saltbox.io/docs/api-gateway/   

API keys allow secure access to API Gateway. Keys are defined at the project level.

Use this page to:

• Generate new keys

• Manage keys
  • Update key names and durations
  • Deactivate/activate keys
    • Deactivated or expired keys can be re-activated manually.
  • Renew keys
    • When a key expires, you can no longer use it to authenticate
    • Manually renew an expired key to extend its duration
  • Regenerate keys
    • When a key is regenerated, it cannot be restored to its old version.
    • This invalidates the key’s previous token and generates a new one.
• Cancel or revoke existing keys. Once cancelled, a key cannot be re-activated.

API keys include:

• Key name - Differentiates one key from another.

  • This name isn't used when authenticating; it’s an administrative label only.

• API key - Used to authenticate.
  • Example: x0cw3r+D0jdiA9/7nw2ckS0jSrohq/nGiU9lFGCD4gUJAjmDeYK7a3vQFaB9axL/

• Duration - When this date is reached, the key expires.

  • Use key management to extend the date on an existing key.

• Status (active, inactive, or cancelled) - Indicates whether the key can be used to authenticate connections to API Gateway.

Testing Tools

You can test Saltbox API Gateway using API utilities such as Postman.

You can use Saltbox itself to test workflow logic (e.g., using static sample files and the 'Route Workflow' action from the core connector). You can use this approach to automate testing after updating workflow logic that supports a Saltbox API.

Error Codes

HTTP response code 400

This error is returned when the workflow’s input message is in the wrong format, such as:

• Incorrect Message Format is set on the workflow trigger.

  • For example, when this is set to “XML” but the request body is formatted in JSON.

• Request body data is in the wrong format.

  • For example, when the Message Format expects XML but the request body supplies JSON.

To resolve:

• In Saltbox, go to the "Workflow Trigger" page.

• Inspect the setting: Raw Message Contents > Message Format.

  • If it's not as expected, update this setting (for example, change “XML” to “JSON” or vice versa).

• Inspect the request data.

  • If it's not as expected, correct the data.

• You'll get this error if the message format workflow trigger and the request data don't match.

  • If there are scenarios where multiple formats are supported, these must be set up as separate triggers.

HTTP response code 401

This error is typically caused by an incorrect API key.

• Verify that the API key is correct.

  • In Saltbox, go to Project Settings > API Gateway Settings.

  • Use the quick-copy button to copy the API key automatically.

  • Update the header’s X-Api-Key parameter with this new key.

HTTP response code 403

This error can be caused by an incorrect API key or insufficient access to a project or workflow.

To resolve:

• Verify that the API key is correct.

  • In Saltbox, go to Project Settings > API Gateway Settings.

  • Use the quick-copy button to copy the API key automatically.

  • Update the header’s X-Api-Key parameter with this new key.

• Verify that the project and workflow still exist, and that API Gateway access is still enabled.

  • In Saltbox, go to Project Settings > API Gateway Settings.

    • Ensure that the option Enable AWS API Gateway access for the project is checked.

      • If not, this is the cause of the error. To resolve, enable API Gateway and save.

  • Open the workflow.

  • Go to Workflow Settings.

    • Ensure that the option Enable API Gateway Access is checked.

      • If not, this is the cause of the error. To resolve, enable access and save.

HTTP Response code 404

This error is typically caused by using the incorrect URL.

This can also result when a workflow or project is deleted.

• Verify that the workflow still exists.
  • Log into Saltbox and navigate to the project and workflow.
• If the project and workflow exist, use the quick-copy button to copy the correct URL and attempt the POST again with the fresh URL copy.
• If the project or workflow doesn't exist, this error code is valid.
  • You must use a different project or workflow.

HTTP response code 422

This indicates that a required parameter is missing from the request.

To resolve:

• Confirm that all required parameters are configured, including:

  • In the header: X-Api-Key - ensure this is set to your valid API key.

  • Ensure the request body message type is configured.

  • Ensure the request body data is included.

This indicates that the request was successfully converted into a Saltbox message, but the workflow failed to process it.

To resolve:

• Use Message Trace to investigate the cause of the failure.
  • See Using Message Trace to Troubleshoot Workflows 

HTTP response code 500

This is a general-purpose error message. It is sometimes temporary, so wait briefly, then attempt the API call again.

Due to the unknown nature of this error type, general troubleshooting instructions are outlined below. If the issue persists, you should determine a root cause by analyzing application logs.

• Wait briefly, then attempt to call the API again.

• If the error persists, review the project’s logs in Saltbox.

  • Go to Project Settings > System Information > Logs and search the relevant log for ERROR details.

HTTP response code 503

This error has a few causes:

• The application server is offline or inaccessible (such as behind a firewall).

• The API key is incorrect.

To resolve:

• Confirm that the application server that supports the project is online.

  • In Saltbox, go to the “Manage Integration Engines” page to confirm the status of the “Cloud Engines” or (if applicable) “App Server on EC2”.

    • If the engine or server is offline, attempt to restart it.

• Verify that the API key is correct.

  1. In Saltbox, go to Project Settings > API Gateway Settings.

  2. Use the quick-copy button to copy the API key automatically.

  3. Update the header’s X-Api-Key parameter with this new key.

Previous