Access Token B2B

Overview

This API endpoint is designed for Business-to-Business (B2B) interactions between a Merchant and Manjo. It allows the client (Merchant) to request an OAuth 2.0 access token using the "client_credentials" grant type. This token is essential for authenticating subsequent API calls to protected resources under Manjo's control.

The process follows standard OAuth 2.0 protocols (RFC 6749 & 6750), ensuring secure authentication without user involvement. The token is short-lived (expires in 900 seconds or 15 minutes) to enhance security.

Key Notes:

• This is a POST request to generate a new access token.
• All requests must include cryptographic signatures for integrity and non-repudiation.
• Use this API only when initiating a session or when the current token expires.
• Always handle errors gracefully, especially unauthorized (401) responses, which may require regenerating the signature or checking credentials.
• The API assumes prior registration where the client receives a client_id (X-CLIENT-KEY) and private key for signing.

General Information

• Service Code: 73
• Name: Access Token B2B
• Direction: Merchant to Manjo (Client requests token from Provider).
• Version: 1.0
• HTTP Method: POST
• Path: /v1.0/access-token/b2b

Notes on General Info:

• The path is versioned (v1.0) to allow future updates without breaking existing integrations.
• Direction indicates the flow: Merchant acts as the client requesting from Manjo as the token provider.

Request Details

The request consists of specific headers for authentication and timing, and a simple JSON body specifying the grant type.

Headers

These headers are mandatory and ensure the request's authenticity, timing, and content type.

Field	Attribute (M/O/C)	Type	Description	Keterangan / Notes
Content-Type	M	String	Represents the media type of the resource (e.g., application/json, application/pdf).	Set to application/json. This tells the server to expect JSON in the body. Note: Using other types will result in errors.
X-TIMESTAMP	M	String	Client's current local time in yyyy-MM-ddTHH:mm:ssTZD format (e.g., 2025-11-27T08:05:41+07:00).	Format must include timezone (TZD, e.g., +07:00). This prevents replay attacks by ensuring timeliness. Tip: Use UTC or local time consistently to avoid mismatches.
X-CLIENT-KEY	M	String	Client’s client_id (PJP Name) provided during registration.	For APIs where Manjo is the provider, use the Client ID from merchant data. For Manjo as client, use Merchant's Client ID. This identifies the requester.
X-SIGNATURE	M	String	Non-Repudiation & Integrity checking using asymmetric signature SHA256withRSA. Formula: Sign with Private_Key over stringToSign = client_ID + “|” + X-TIMESTAMP.	Ensures the request hasn't been tampered with. Generate using your private key (obtained during registration). Common issue: Mismatched timestamp or client key leads to invalid signature errors.

Notes on Headers:

• All headers are case-sensitive.
• The signature is critical for security; always regenerate it for each request as it depends on the timestamp.
• If the timestamp is too old (e.g., >5 minutes skew), the request may be rejected.

Body

The body is a JSON object with a single mandatory field.

Field	Attribute (M/O/C)	Type	Description	Keterangan / Notes
grantType	M	String	Must be “client_credentials”. This grant type is for machine-to-machine authentication without user context (OAuth 2.0: RFC 6749 & 6750).	Fixed value: "client_credentials". Using other values will cause invalid request errors. This is suitable for server-side integrations.

Notes on Body:

• Keep the body minimal; extra fields may cause validation failures.
• Ensure JSON is well-formed and UTF-8 encoded.

Example Request

This example shows a complete request with sample values. Replace with your actual data.

POST /api/v1/access-token/b2b HTTP/1.1
X-CLIENT-KEY: EP9613058999
X-SIGNATURE: b634c01386f0234c984e142bb72a50894336fd1ffebb67f3db16f16c776d02cd661c4e5e50169b04d5f06d7c4c53f924289d378a1f790287ef7f975e4bb2b16c74f5afea4a590bcb7d45ea6ad6e1ba85a589bee411cb15da497bd880f7fa4a52caf435714f726ed3e325268ea01e682e1ae82592758368ccc24c9b3bffc4ec0a19f41147f955a891acc8dd29f47485da7e6454b87c477f08b669c4dd8b5b96e2dca612e7cc1c742efd2f39db719948a3355198ba1de206f942b809999fd6cebcba8d9844b9d65543e48b0c5a9dfa81f3d481773ff547f875d58c9ab9271de8241386d35ae8224ad14d6442a57220f09d57c5247d8bf1eda28d5d5afe4eb07fe0
X-TIMESTAMP: 2025-11-27T08:05:41+07:00
Content-Type: application/json

{
  "grantType": "client_credentials"
}

Notes on Example:

• The X-SIGNATURE is a long hex string generated from the formula. Use a library like Java's RSA or Python's cryptography to compute it.
• Test in a tool like Postman, ensuring headers are set correctly.

Response Details

The response mirrors some request headers and provides the token in the body if successful.

Headers

Field	Attribute (M/O/C)	Type	Description	Keterangan / Notes
X-TIMESTAMP	M	String	Echo of the client's timestamp in yyyy-MM-ddTHH:mm:ssTZD format.	Format: yyyy-MM-ddTHH:mm:ssTZD. Used for logging or verification.
X-CLIENT-KEY	M	String	Echo of the client's client_id.	Echo from request. Helps in tracing.

Notes on Response Headers:

• These are for consistency and auditing; no action needed on the client side.

Body

The body is a JSON object with success details or error information.

Field	Attribute (M/O/C)	Type	Description	Keterangan / Notes
responseCode	C	String	Standard response code (see Error Codes section). Conditional: Present if token generation fails.	Format: httpcode(3)+Servicecode(2)+casecode(2). Use to determine success/failure programmatically.
responseMessage	C	String	Human-readable message corresponding to the responseCode. Conditional: Present on failure.	Provides details like "Successful" or error reasons. Log this for debugging.
accessToken	M	String (2048)	The bearer token string for authorizing future requests.	Base64-encoded or similar. Store securely and use in Authorization header as "Bearer ".
tokenType	M	String	Type of token, typically "Bearer". Other types like "Mac" possible but not used here. Reference: OAuth2.0 RFC 6749 & 6750.	Fixed to "Bearer" for this API. Include in Authorization: "Bearer ".
expiresIn	M	String	Token expiry time in seconds (e.g., "900" for 15 minutes).	Plan to refresh the token before expiry to avoid interruptions.

Notes on Body:

• On success, expect HTTP 200 with token details.
• On failure, HTTP error code with responseCode and message.
• The accessToken is sensitive; never log or expose it.

Example Response

Successful response:

{
    "responseCode": "2007300",
    "responseMessage": "Successful",
    "tokenType": "Bearer",
    "accessToken": "YWFlNTQ4NTEyZTE5ZjZiY2MxN2E2Y2Y5NDVkY2UzNmU6MDA6Zjg1YTI5MjhlYjU2NDg4Zjk3YzIwODFkYTI3ZTY4ZWRnQ1Vid2hRanJkOGx5Y1owNHlMMmxTMEFTenN2bnZUaA==",
    "expiresIn": "900"
}

Notes on Example:

• Use the accessToken immediately in subsequent calls.
• If expiresIn is "900", set a timer to refresh after ~14 minutes.

Error Codes

Errors follow a structured format: httpcode(3)+Servicecode(2)+casecode(2). Refer to standard specs part 6 for full details.

HTTP Code	Service Code	Case Code	Message Category	Description / Notes
200	73	00	Success	Successful. Indicates token generated successfully.
400	73	01	Message	Invalid Field Format {field name}. E.g., wrong timestamp format. Check field types.
400	73	02	Message	Invalid Mandatory Field {field name}. Missing/invalid header or body (e.g., no grantType). Ensure all M fields are present.
401	73	00	System	Unauthorized. {reason}. General auth error: invalid signature or client key. Regenerate signature.
401	73	01	System	Invalid token. Token in request invalid (not exist or expired). Note: This might refer to re-requesting if using an old token.
409	51	00	System	Conflict. Cannot use same X-EXTERNAL-ID in same day. (Note: This seems unrelated to service 73; possibly a copy-paste error from another spec. Ignore if not applicable.)

Notes on Error Codes:

• Always check HTTP status first, then responseCode for specifics.
• For 401 errors, common fixes: Verify private key, timestamp sync, and client_id.
• Log full responseMessage for troubleshooting.
• If encountering undocumented codes, refer to the full OAuth specs or contact support.

Additional Notes

• Security Best Practices: Use HTTPS only. Rotate keys periodically. Store tokens in memory, not persistently.
• Testing: Use sandbox environments if available. Mock signatures for local testing.
• Rate Limiting: Not specified; assume standard limits—monitor for 429 errors.
• Dependencies: Requires prior registration with Manjo for client_id and private key.
• Further Reading: OAuth 2.0 RFC 6749 for grant types; RFC 6750 for bearer tokens. For signature generation, use standard crypto libraries.

This documentation aims to be self-contained. If anything is unclear, provide feedback on specific sections!