Beyond Sandbox

Authentication & Authorization

The Emtech API uses a secure OAuth 2.0-inspired flow. To interact with our resources, developers must first exchange their application credentials for a temporary Access Token and then include that token in the headers of all subsequent API requests.

Step 1: Generate an Access Token

To authenticate, send a POST request to the token endpoint using the credentials found on your App Details page.

Endpoint: POST https://api.emtech.com/integration/v1/auth/token

Request Body

Code
 
{
  "clientId": "{App client Id}",
  "clientSecret": "{App client secret}"
}

Response

Code
 
{
  "accessToken": "eyJhbGciOiJIUzI1...",
  "expiryMS": 3600000
}

Step 2: Use the Token in API Calls

Once you have obtained the accessToken, you must pass it in the header of all subsequent API requests.

Instead of the standard Authorization header, this API requires a custom header key: x-sandbox-app-auth.

Header Requirements

Header Key	Value Format
`x-sandbox-app-auth`	`Bearer {accessToken}`

Troubleshooting: Common Error Codes

If your authentication or API call fails, refer to this table to resolve the issue:

Status Code	Meaning	Common Cause	Recommended Action
400 Bad Request	Malformed Request	Missing `clientId` or `clientSecret` in the request body.	Check your JSON syntax and field names.
401 Unauthorized	Invalid Credentials	Incorrect `clientSecret` or an expired/malformed token.	Re-generate the token or check for the "Bearer " prefix.
403 Forbidden	Access Denied	The token is valid, but your app lacks permissions for this resource.	Verify your App's scope on the dashboard.
415 Unsupported Media Type	Missing Content-Type	The `Content-Type: application/json` header is missing.	Add the required header to your request.

Checklist for Success

Verify Header Key: Ensure you are using x-sandbox-app-auth (case-sensitive).
Check Prefix: Confirm there is a space between Bearer and the token.
Handle Expiry: Implement logic to refresh the token when expiryMS is reached.
Secure Secrets: Never share or hard-code your clientSecret in frontend applications.

Overview