Get Your Access Token

This endpoint is used to authenticate a client by providing a clientId and clientSecret. If successful, the response contains a JWT bearer token that can be used to authenticate subsequent API requests to protected endpoints. The token is valid for a limited time and should be included in the Authorization header of future API requests.

Endpoint: POST /api/v1/auth/authenticate

Request

• URL: /api/v1/auth/authenticate
• Method: POST
• Content-Type: application/json

Headers:

Content-Type: application/json

Sample Payload:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Request Parameters:

• clientId (string): The client ID provided during the registration process.
• clientSecret (string): The client secret associated with the client ID.

Response

• Status: 200 OK

Sample Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "bearer",
  "expiresIn": 3600
}

Response Fields:

• accessToken (string): The JWT token used to authenticate subsequent requests.
• tokenType (string): The type of token returned. Typically, this will be "bearer".
• expiresIn (integer): The number of seconds the token is valid for before expiration. For example, 3600 seconds means the token is valid for 1 hour.

Possible HTTP Status Codes

• 200 OK: Authentication successful, and a valid JWT token is returned.
• 400 Bad Request: Invalid input data (e.g., missing clientId or clientSecret).
• 401 Unauthorized: Authentication failed due to invalid clientId or clientSecret.
• 500 Internal Server Error: An error occurred on the server while processing the request.

Usage Example

1. Authenticate and Receive JWT Token
   Send a POST request to the /authenticate endpoint with valid credentials:

   HTTP

   POST /api/v1/authenticate HTTP/1.1
   Host: api.epgl.ae
   Content-Type: application/json
   {
     "clientId": "your-client-id",
     "clientSecret": "your-client-secret"
   }

   Response:

   JSON

   {
     "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "tokenType": "bearer",
     "expiresIn": 3600
   }

2. Use JWT Token for Authentication in Subsequent Requests
   Include the JWT token in the Authorization header for all subsequent API requests:

   HTTP

   POST /api/v1/secure-endpoint HTTP/1.1
   Host: api.epgl.ae
   Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration and Renewal

• The returned JWT token is valid for the duration specified in the expiresIn field (typically 3600 seconds or 1 hour). Once the token expires, you will need to re-authenticate by calling the /authenticate endpoint again with your clientId and clientSecret to obtain a new token.
• Ensure your integration handles token expiration gracefully by either refreshing the token proactively or responding to 401 Unauthorized errors by re-authenticating.

Additional Notes

• Security Considerations: Keep your clientId and clientSecret secure. Do not expose them in client-side code or public repositories. Use environment variables or secure vaults for storing credentials.
• Rate Limiting: This endpoint is subject to rate limiting. Avoid making excessive authentication requests. In case of a 429 Too Many Requests error, follow the retry guidelines provided in the response headers.

By following this guide, you'll be able to securely obtain and manage authentication tokens for accessing protected resources on the platform.