Skip to main content

Authentication with XGS APIs

APIs require authentication to ensure that only authorized users have access. For the XGS APIs, a Bearer token is used to authenticate requests through a token that confirms the user’s identity. This guide covers the basics of authentication, how to obtain a token, and how to use it to access XGS APIs.

Step 1: Understanding the Authentication Endpoint​

The endpoint for retrieving an authentication token is:

  • Endpoint: POST /authentication/user/token
  • Host: srvcs.xgsi.com
  • Port: 443
  • Operation: Retrieves a Bearer token that grants access to the XGS APIs.

To retrieve a token, send a POST request with the required user credentials in the body.

Step 2: Requesting a Token​

To obtain the token, provide two essential pieces of information in the request body:

  • id: Your user ID for XGS API access.
  • pw: Your password for XGS API access.

Example Request​

Here’s an example of how the request might look when retrieving a token:

POST /authentication/user/token
Host: srvcs.xgsi.com
Content-Type: application/json

{
  "id": "yourUserID",
  "pw": "yourPassword"
}

Response Format​

If the credentials are correct, the server responds with a JSON object containing:

  • access_token: The token string to authenticate further requests.
  • token_type: The type of token (e.g., "Bearer").
  • expires_in: The token’s expiration time in seconds.

Example Response​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "expires_in": 3600
}

This response indicates that you have a valid token (access_token) with a "Bearer" type, which is valid for 3600 seconds (1 hour).

Step 3: Using the Token in API Requests​

Once you have the access_token, use it to access other XGS API endpoints by including it in the Authorization header of each request.

Example: Accessing an Authenticated Endpoint​

To access a protected endpoint, such as retrieving probill details, include the token as follows:

GET /agent/probill?probillNumber=12345 HTTP/1.1
Host: srvcs.xgsi.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI...

In this request:

  • Replace eyJhbGciOiJIUzI1NiIsInR5cCI... with the actual access_token value you received.
  • The server will authenticate the request and allow access to the resource if the token is valid.

Handling Token Expiration​

Tokens come with an expiration time, as indicated by the expires_in value. After this time, the token will no longer be valid, and you’ll need to request a new token by re-authenticating. Many API clients automatically refresh tokens when they expire, but if yours doesn’t, you’ll need to handle token renewal in your application.

tip

Along with expiry time also use the APIs response to trigger token generation when a 401/403 response code is received.

Error Handling​

If authentication fails, the server will respond with an error response(example: No token in response mesage or response with http code 500), indicating there was an error in processing the request. This could be due to incorrect credentials, missing fields in the request body, or other issues.

Summary​

To authenticate with the XGS APIs:

  1. Request a Token: Send a POST request to /authentication/user/token with your user ID and password.
  2. Receive and Store the Token: The server responds with an access_token that’s valid for a specified time.
  3. Access Protected Endpoints: Include the token in the Authorization header of subsequent requests.
  4. Renew the Token: After the token expires, repeat the authentication process to obtain a new token.

By following these steps, you can ensure secure, authenticated access to XGS APIs for your logistics operations.