ShipX provides a GraphQL API that requires each request to be authenticated using a signed JWT (JSON Web Token) included in the HTTP Authorization header. The JWT is generated per request and must include a hash of the request payload, as well as standard claims such as iat (issued at) and exp (expiration). This ensures both the authenticity and integrity of each API call.

Authentication is performed by including the following HTTP header:

The JWT must be signed using your provided secret or private key, and the payload must contain the following fields described in step 2 below. Here is an example digram of how it's broken down. 

Endpoint:

POST https://public-api.shipx.cc/api // For Production
POST https://uat-public-api.shipx.cc/api // For UAT
POST https://staging-public-api.shipx.cc/api // For Staging

Headers:

1. Content-Type: application/json

2. Authorization: Bearer <JWT_TOKEN>

JWT Generation

1. Generate payloadHash:
   1. Hash the raw GraphQL request body (as a string) using the algorithm specified (e.g., sha256).
   2. Example (Node.js):

      1. const crypto = require('crypto');
         const payload = JSON.stringify({ query, variables });
         const payloadHash = crypto.createHash('sha256').update(payload).digest('hex');

   3. Example (VB)
      1. See document here.
2. JWT Payload Fields:
   • iat: Issued at time (Unix timestamp, seconds).
   • exp: Expiration time (Unix timestamp, seconds). Should be within 10 minutes of iat.
   • portalCompanyUuid: Your portal company UUID.
   • baseCompanyUuid: Your base company UUID.
   • payloadHash: The hash from step 1.
   • Example:

     • {
         "iat": 1714300000,
         "exp": 1714300600,
         "portalCompanyUuid": "your-portal-company-uuid",
         "baseCompanyUuid": "your-base-company-uuid",
         "payloadHash": "abcdef1234567890..."
       }
       
       

3. Sign the JWT
   1. Use your provided secret or private key. To learn how to generate a key pair, see here. Ensure to paste the public key where you replace the end line character with \n. 
   2. Example (Node.js, using jsonwebtoken)

      1. const jwt = require('jsonwebtoken');
         const token = jwt.sign(jwtPayload, secretOrPrivateKey);

4. Include JWT in the Authorization Header:

   1. Authorization: Bearer <token>

Example Request

POST https://shipx.cc/graphql
Content-Type: application/json
Authorization: Bearer <token>


{
  "query": "...",
  "variables": { ... }
}

Notes:

• The JWT must be generated for each request, as the payloadHash must match the body.
• iat and exp are required and should be set to the current time and current time + 10 minutes, respectively.
• If the JWT is invalid or expired, the request will be rejected.

Testing

To ease the integration testing we have developed a test route in staging that allows you to send the data to your server or our staging server. It will use your private key and post to our server to validate the algorithm. This only works for staging.