Authentication

Authentication is a crucial process in securing access to the Huch API. This section explains the authentication process in detail:

1. Purpose of the Endpoint:

   • This endpoint is specifically designed to authenticate your application and provide you with an access token.
   • The access token serves as a temporary credential that grants your application permission to interact with the Huch API.

2. Access Token Lifecycle:

   • Once obtained, the access token remains valid for 1 hour.
   • This time-limited validity enhances security by reducing the window of opportunity for potential misuse.

3. Using the Access Token:

   • You must include this access token in all subsequent requests to the Huch API.
   • The token acts as a proof of authentication, allowing the API to verify your application's identity and permissions.

4. Token Expiration and Renewal:

   • After the 1-hour validity period, the access token will expire.
   • When this happens, your application will need to request a new access token to continue accessing the API.
   • It's recommended to implement a mechanism in your application to automatically refresh the token before or upon expiration.

Obtaining Credentials

To start using the Huch API, you need to obtain two essential pieces of information:

1. How to Get Credentials:

   • Please contact our support team to receive your unique Client ID and Client Secret.
   • Our team will verify your identity and provide you with these credentials securely.

2. Merchant ID:

   • The Merchant ID is a public identifier for your application.
   • It is used in conjunction with your Client Secret to authenticate your application.
   • While not as sensitive as the Client Secret, it's still advisable to handle it with care.

3. Client Secret:

   • The Client Secret is a confidential authentication key for your application.
   • It must be kept strictly confidential and secure at all times.
   • Never expose your Client Secret in public repositories, client-side code, or any unsecured location.

4. Client ID:

   • The Client ID is a public identifier for your application.
   • It is used in conjunction with your Client Secret to authenticate your application.
   • While not as sensitive as the Client Secret, it's still advisable to handle it with care.

Security Warning

CAUTION

Do not share your Client Secret in publicly accessible areas such as GitHub, client-side code, etc.

Best Practices for Credential Management

To ensure the security of your application and the Huch API:

1. Secure Storage: Store credentials in secure, encrypted environments.
2. Environment Variables: Use environment variables to store sensitive information.
3. Access Control: Implement strict access controls for credential access.
4. Regular Rotation: Periodically rotate your Client Secret to minimize risk.
5. Monitoring: Implement logging and monitoring for credential usage.

Endpoint POST

Sandbox

/api/oauth2/token

Production

/api/oauth2/token

headers

'Accept: application/json'
'Content-Type: application/x-www-form-urlencoded'

Body parameter x-www-form-urlencoded

grant_type: client_credentials
client_id: xxxxxxxx
client_secret: xxxxxxxxxxxxxxxxxxx

Request an access token

Request an access token with the following code:

HTTP Code sample

cURLPHPJavaScript

1curl --location --request POST 'https://api-gateway-sandbox.huch.tech/api/oauth2/token' \
2--header 'Accept: application/json' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--data-urlencode 'grant_type=client_credentials' \
5--data-urlencode 'client_id=' \
6--data-urlencode 'client_secret='
7

Response example

{
  "access_token": "eyJraWQiOiJodDEwY3dDS01ueE41ME5aR054ZHFHT2pSTHZkaXFEelFjS05paWdHM2dzPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIyc23MmJnbnVua2lxcGM3dGpoMjZkcHUydSIsInRva2VuX3VzZSI33jY2VzcyIsInNjb3BlIjoiYXBwX3VzZXJcL2FwcF91c2VyIiwiYXV0aF90aW1lIjoxNzI4MDU3Nzc0LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0zLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtM19kdGFSUW9TNEQiLCJleHAiOjE3MjgwNjEzNzQsImlhdCI6MTcyODA1Nzc3NCwidmVyc2lvbiI6Miw32nRpIjoiNWQzM2VhZDEtY2Q1Yi00YzU0LWI0MDAtMGVmMTA0MGMzMWM0IiwiY2xpd30X2lkIjoiMnBlYTJiZ251bmtpcXBjN3RqaDI2ZHB1MnUifQ.b_zVgxJukcRMvCkgC7KYf5mJWIPSWEDG08ictNskAVCV8qER-I5Xtkvj-x1u-BCgbER_l6NrecQwJ_kZMEsZRI-kNma9t-Wv5uVD4o348WAgD4yHPdp0yz4cXPn4hkgQoCosUqOJfGrPFnde2JoJT3QPMeUV8usM729CC4vYCNq5hr-xEJpzdPTI9X-H9yqMpUb75l6Vouh8hIIu3S_lFq3HXF-NwByYbI9K5wPvEpKcCkBU0VNLLJ7Iq2nsOS532cQn2oWZWH7OrzEazgpFu1H3gF7qkDfUwpn2mPQMtF_uUQ3PCezw0QSV9FE8XPEJFbT8JERCaE_8bqcbsPtA",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Invalid Access Token Response

WARNING

When using an invalid token to make requests to any API endpoint such as:

• Make a payout or deposit
• Get a payment status or get a payout status
• Everything else

You will get one of the following responses:

400 Bad Request

Code: 400

1. Invalid Access Token : "kid" empty, unable to lookup correct key

{
    "message": "Invalid Access Token : \"kid\" empty, unable to lookup correct key"
}

2. Invalid Access Token : Expired token

"Invalid Access Token : Expired token"

3. Access Token missing

 
"Access Token missing"

Errors

Error code	Meaning
400	Required information is missing
401	Incorrect login information
404	Account not found
500	Internal system error

See the Errors & Error Codes page for the shared error format, the X-Request-ID correlation header, and retry guidance.