Reference for Saltbox API Gateway

This reference aims to provide technical details about Saltbox API Gateway. For tutorials or walkthroughs, see: Saltbox API Gateway Overview.

API Gateway Key Management

API Keys are used to 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. Keys that are deactivated or keys that have expired can be re-activated manually.
    • Renew keys. When a key expires, it can no longer be used 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 in its place.
  • Cancel or Revoke existing keys. Once cancelled, a key cannot be re-activated.

API Keys include:

  • Key Name - used to identify one key from another. This name is not used when authenticating, it’s an administrative label only.

  • API Key - used when authenticating.
    • Example: x0cw3r+D0jdiA9/7nw2ckS0jSrohq/nGiU9lFGCD4gUJAjmDeYK7a3vQFaB9axL/
  • Duration - When this date is reached, the key will no longer work. Use key management to extend this date on an existing key.

  • Status (Active, Inactive or Cancelled) - Indicates whether or not the key may be used to authenticate connections to API Gateway.

Testing Tools

Saltbox API Gateway can be tested using API utilities. One such tool is Postman.

Saltbox itself can be used to test of workflow logic, for example, using static sample files and the Route Workflow action from the Core Connector. This approach can be used to automate testing after updating workflow logic that supports a Saltbox API.

Error Codes

HTTP Response Code Error / Description
400 Content not in expected format

This error is returned when the workflow’s input message is in the wrong format.
401 Unauthorized, The platform API token Key is not valid

This error is typically caused by an incorrect API key.
403 Forbidden, User is not authorized to access this resource with an explicit deny

This error can be caused by an incorrect API key or insufficient access to a project or workflow.
404 The specified Project \ Project Version doesn't exist

This error is typically caused by using the incorrect URL.
422 Missing parameters

This indicates that the message was un-processable in some way. See response details for a root cause.
422 Un-processable message

This indicates that the message was un-processable in some way. See response details for a root cause.
500 unexpected error

This is a general-purpose error message. It is sometimes temporary, so wait briefly before attempting the API call again.
503 Integration Application Server was unavailable or Attempt to access Integration Application Server was unauthorized

This error indicates that access was unsuccessful, for example, if the supporting application server is offline.