Host Information

Production Host: api.twoboxes.io

Authentication & Authorization

Authentication

API requests are authenticated using bearer tokens obtained via Two Boxes API and a service account client ID and secret:

1. Email Two Boxes support requesting a machine user for your 3PL.

2. Two Boxes will provide you:

   1. Machine User Client ID
   2. Machine User Secret
   3. Two Boxes 3PL ID

3. Obtain a token via the API

   POST twoboxes.api.io/api/v1/users/token
   Content-Type: application/x-www-form-urlencoded

   JSON

   {
      "client_id": "from step 2 A",
      "client_secret": "from step 2 B",
      "grant_type": "client_credentials",
      "3pl_id": "from step 2 C"
   }

   On success, an HTTP 200 will be returned with a JSON body that includes a "token" property.

    {
       "access_token": "{string}",
       "expires_in": "{int seconds}",
       "token_type": "bearer"
    }

4. Use the "token" value from step 3 on subsequent Two Boxes API requests in in an Authorization header
   Authorization: BEARER "token value"

Tokens currently expire after 90 minutes and require a new call to POST api.twoboxes.io/api/v1/users/token .
If a token is expired, API_NOT_AUTHENTICATED error with HTTP status code 401

Authorization

Authorization of users is managed via IAM-based permissions. Machine users that Two Boxes creates on your behalf will have access to all resources at the 3PL. If more granular access is required, contact Two Boxes support and permission scopes will be updated.

Note: There is no limit on the number of machine users in an organization.

Rate-Limiting & Long Running Requests

Current rate limit is set to 100 requests per minute

If a request takes longer than 30s, Two Boxes will drop the socket.

API Design Principles

The Two Boxes API uses REST principles with JSON payloads.

Two Boxes uses relaxed parsing on inbound schemas, meaning any unexpected fields are dropped
without error.

Two Boxes uses static schemas on outbound, meaning that null or empty fields will still be present in response bodies (in other words, "omit empty" serialization is NOT employed).

For all Two Boxes API endpoints using the GET request method, all query parameters are optional and any payloads in the body will throw an error.

Note: The Two Boxes API uses different semantic principles than the Two Boxes Partner
Portal. That is, the Partner Portal operations may make simplifications and/or option-chains
for UX ease-of-use purposes. Be sure to read the Two Boxes API documentation to understand
the API's operation semantics.

Errors

Two Boxes uses a modified version of Problem Details defined in RFC 7807. Payloads include a human-readable (for debugging only) message, and a machine-readable code:

{
   "cause": "nullable; embedded error payload for root cause",
   "errorCode": "ENUMERATED_VALUE",
   "errorMessage": "Human readable debugging information",
   "httpStatus": "integer value",
   "metaData": "nullable; error-specific hints"
}   

Except in rare cases, enumerated error codes will always only have one HTTP status associated with them, and if an error has metadata, those metadata properties are static.