Authentication

POST /v4/auth/token

Purpose:
Authenticates API clients and generates OAuth 2.0 Bearer tokens for authorized platform access.

This endpoint serves as the entry point for all platform interactions, implementing the OAuth 2.0 client credentials flow to verify partner identity and establish secure sessions. Partners submit their client credentials (client ID and secret) along with requested access scopes, and receive a JWT Bearer token that must be included in all subsequent API requests. The endpoint validates credentials against the partner registry, applies appropriate access permissions based on partner agreements, and generates tokens with configurable expiration times. The authentication process includes comprehensive logging for security monitoring and supports various token scopes that limit access to specific platform functionality based on partner agreements and compliance requirements. This centralized authentication approach ensures 16 consistent security across all platform services while enabling granular access control and audit capabilities essential for enterprise operations

Request (cURL)

curl -X POST https://api.rc.saas.bolttech.asia/v4/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "partner_client_12345",
    "client_secret": "sk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "grant_type": "client_credentials",
    "scope": "openid"
  }'

Request Payload (JSON)

{
  "client_id": "partner_client_12345",
  "client_secret": "sk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "grant_type": "client_credentials",
  "scope": "openid"
}

---

200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwYXJ0bmVyX...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "openid"
}

400 Bad Request

{
  "error": "invalid_request",
  "error_description": "missing or invalid client credentials"
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "client authentication failed"
}

---

Notes

• grant_type: Only client_credentials is supported.
• scope: Defines access to platform services (e.g., openid, policies:read).
• expires_in: Default 3600 seconds (1h), configurable per partner.
• Security: Full request and response logging for audit & compliance.

Encryption/Decryption

Security

The security model uses asymmetric cryptography with RSA key pairs exchanged between the Partner and Bolttech.

Key Exchange Process:

• Partner generates RSA key pair (private/public)
• Bolttech generates RSA key pair (private/public)
• Public keys are exchanged between both parties
• Private keys remain secure and are never shared

Request Flow:

1. Partner creates payload
2. Encrypts payload with Bolttech's public key
3. Signs encrypted payload with Partner's private key
4. Sends signed, encrypted request
5. Bolttech validates signature using Partner's public key
6. Bolttech decrypts payload using their private key

Response Flow:

1. Bolttech encrypts response with Partner's public key
2. Signs response with Bolttech's private key
3. Partner validates signature using Bolttech's public key
4. Partner decrypts response using their private key

---

##Encryption

Asymmetric cryptography ensures all payloads exchanged with the gateway are protected.

Encryption Specifications

• Algorithm: RSA
• Key Size: 2048 or 4096 bits
• Padding: RSA_PKCS1_OAEP_PADDING
• Hash: SHA256

Key Management

• The Bolttech API consumer creates an RSA key pair
• Private keys must be kept in secure, offline storage
• Only public keys are shared between teams
• The payload is encrypted with Bolttech's public key
• Bolttech decrypts requests with their private key

Node.js Encryption Example

const crypto = require("crypto");

// Public key shared by Bolttech API team
const bolttechPublicKey = `-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----`;

// Sample payload
const payload = {
  "misdn": "600123123",
  "posSfid": "17000088",
  "posUser": "FCMJint1",
  "posDueDate": "12/2023",
  "productId": "1.5.1.3",
  "smsCampaign": "campaign name",
  "uuid": "123Abc",
  "channel": "ChannelABC"
};

// Encrypt the payload
const encrypted = crypto.publicEncrypt(
  {
    key: bolttechPublicKey,
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "sha256",
  },
  Buffer.from(JSON.stringify(payload))
);

// Base64 encode for transmission
const encryptedPayload = encrypted.toString("base64");
console.log(encryptedPayload);

---

##Decryption

Responses from the Bolttech API are encrypted using your public key and can only be decrypted with your private key.

Decryption Specifications

• Algorithm: RSA
• Key Size: 2048 or 4096 bits
• Padding: RSA_PKCS1_OAEP_PADDING
• Hash: SHA256

Key Management

• Share your public key with the Bolttech API team
• Keep your private key secure and offline
• Bolttech encrypts all responses with your public key
• Decrypt responses using your private key

Node.js Decryption Example

const crypto = require("crypto");

// Your private key (keep secure!)
const yourPrivateKey = `-----BEGIN ENCRYPTED PRIVATE KEY-----
...
-----END ENCRYPTED PRIVATE KEY-----`;

// Encrypted response from Bolttech API
const encryptedResponse = "l50M6G92x9itoluzqLYknq..."; // Base64 string

// Decrypt the response
const decrypted = crypto.privateDecrypt(
  {
    key: yourPrivateKey,
    passphrase: "your-secure-passphrase",
    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: "sha256",
  },
  Buffer.from(encryptedResponse, "base64")
);

// Parse the decrypted JSON
const responseData = JSON.parse(decrypted.toString());
console.log(responseData);

---

Signing Payload

JSON Web Token (JWT) is used to sign payloads, providing cryptographic verification that the payload hasn't been tampered with.

Signing Specifications

• Standard: RFC 7519 (JWT)
• Algorithm: RS256 (RSA with SHA256)
• Sign the encrypted payload with your private key
• Share your public key with Bolttech for signature validation

Generating RSA Key Pair (Node.js)

const NodeRSA = require('node-rsa');

// Generate new key pair (do this once)
const rsa = new NodeRSA();
const keys = rsa.generateKeyPair();

// Export private key (keep secure!)
const privateKey = keys.exportKey();

// Export public key (share with Bolttech)
const publicKey = keys.exportKey('pkcs8-public-pem');

console.log("Share this public key with Bolttech:");
console.log(publicKey);

Signing Encrypted Payload (Node.js)

const jwt = require('jsonwebtoken');

// Your private key from key generation
const privateKey = `-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----`;

// Encrypted data from encryption step
const encryptedData = "3rHECZcvGTRUxp8ijwCXfsBghWyXij...";

// Sign the encrypted payload
const signedPayload = jwt.sign(
  { payload: encryptedData }, 
  privateKey, 
  { algorithm: 'RS256' }
);

console.log("Signed payload ready for API:");
console.log(signedPayload);

---

##Authentication

Before calling API endpoints, you must authenticate to receive a bearer token.

Endpoint

POST /auth/token

Request Example

curl --location --request POST ' https://api.rc.saas.bolttech.asia/v4/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'clientId={{clientId}}' \
--data-urlencode 'clientSecret={{clientSecret}}' \
--data-urlencode 'grantType=client_credentials' \
--data-urlencode 'scope=openid accountId username roles permissions status entityUser'

Request Parameters

Field	Type	Description	Example	Required
clientId	String	Client ID provided by Bolttech	AAfA3KunhIS_CylJBBBay	Yes
clientSecret	String	Client Secret provided by Bolttech	a1234ed056f78a91011baf1e32881213	Yes
grantType	String	OAuth 2.0 grant type	client_credentials	Yes
scope	String	Requested permission scopes	openid accountId username roles permissions status entityUser	Yes

Response Example

{
  "scope": "openid accountId username roles permissions status entityUser",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5DtUXCzg15b8VZ...6gthQ1avGVIDLKpRpL5tPor3Ga2bkE26SGFgqbbZNlHtitd1-4A",
  "expiresIn": 600,
  "tokenType": "Bearer"
}

Response Fields

Field	Type	Description	Example
scope	String	Granted permission scopes	openid accountId username...
accessToken	String	JWT bearer token for API authentication	eyJhbGciOiJSUzI1NiIsInR5cCI6...
expiresIn	Integer	Token expiration time in seconds	600
tokenType	String	Token type	Bearer

---

##Create a Lead example

Submit a new insurance lead to the Bolttech system.

Endpoint

POST  https://api.rc.saas.bolttech.asia/v4/leads

Headers

Authorization: Bearer {accessToken}
Content-Type: application/json

Note: Include the access token from the authentication endpoint in the Authorization header.

Unencrypted Payload Example

{
  "misdn": "600123123",
  "posSfid": "17000088",
  "posUser": "FCMJint1",
  "posDueDate": "12/2023",
  "productId": "1.5.1.3",
  "smsCampaign": "campaign name",
  "uuid": "123Abc",
  "channel": "ChannelABC"
}

Request Parameters

Field	Type	Description	Example	Required
misdn	String	Mobile phone number	600123123	Yes
posSfid	String	Salesforce ID	17000088	Yes
posUser	String	Commercial agent identifier	FCMJint1	Yes
posDueDate	String	Insurance due date (MM/YYYY)	12/2023	Yes
productId	String	Product identifier	1.5.1.3	Yes
smsCampaign	String	SMS campaign name	campaign name	Optional
uuid	String	Unique identifier	123Abc	Optional
channel	String	Channel name	CHANNEABC	Yes

Encrypted Request Example

Important: The payload must be encrypted using the process described in Section 3 (Encryption). Send the encrypted payload in the data attribute.

{
  "data": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjoiVVFjelVZLytGYXg1aCtZNEt1LzNqRWtHTW5TZjY3U1pYcHlLaEQ5M3l2TkZFdEhtV0MrUjJrQURVV0J3RHZ4eVRFZ1JYa0IvbG5pTXNTcXlHdkVMMHo5dVdZUnNvWlFHSWJiK0luSlNNOXZMNEwwVzB5Q2ZQeUM2OTI3Y0lqcnQ2bm9TbFJXZ3BSUGp1d094TkZWNUhuVllzclRjK1ZwVHdCTzg0L05nYVlVT0RuZGJFTDBROFZvNXJ4UW1xM0U2akVKMkh5STZJL3VxbVkyTlZyUE04TGh5Y1Y1UUREdncxdU5pU3BsL2JEY3RkUTd0..."
}

Response Example (Success)

{
  "success": true,
  "data": { 
    "status": "SUCCESS",
    "message": "The lead was created with success"
  }
}

Response Fields

Field	Type	Description	Possible Values
success	Boolean	Indicates if operation succeeded	true / false
data.status	String	Operation status	SUCCESS / FAILED
data.message	String	Human-readable result message	The lead was created with success / The lead was not created

HTTP Status Codes

• 201 Created - Lead successfully created
• 400 Bad Request - Invalid payload or missing required fields
• 401 Unauthorized - Invalid or expired access token
• 500 Internal Server Error - Server-side error

---

Integration Checklist

• Generate RSA key pair (2048 or 4096 bits)
• Share your public key with Bolttech team
• Receive Bolttech's public key
• Receive clientId and clientSecret from Bolttech
• Implement encryption logic
• Implement decryption logic
• Implement JWT signing (if required)
• Test authentication endpoint
• Test create lead endpoint with encrypted payload
• Implement error handling and retry logic
• Store credentials securely (use environment variables or secrets manager)

---

Support

For technical support or questions about this API integration, please contact the Bolttech integration team.

Documentation Version: 1.0.0
Last Updated: 12/04/2023