Skip to main content

​
Authentication

The Clopos API uses OAuth 2.0 for secure authentication. To interact with the API, submit your credentials to the /auth endpoint to obtain an access token.

​
Prerequisites

Before you can authenticate you will need:
  • Client ID: Your application’s unique identifier
  • Client Secret: Your application’s secret key
  • Brand: The brand identifier you want to access
  • Venue ID: The specific venue you want to access
Contact [email protected] to obtain your client credentials.
All Open API requests should use the unified base URL: https://integrations.clopos.com/open-api/.

​
Authentication Flow

​
Step 1: Obtain an access token

Send a POST request to the authentication endpoint: 
curl -X POST https://integrations.clopos.com/open-api/auth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "brand": "{{brand}}",
    "venue_id": "{{venue_id}}"
  }'
Sandbox credentials:
  • Brand: openapitest
  • Venue ID: 1
  • Client ID: 6553676e0d265ac837e8f79fc
  • Client Secret: seCyF_4vja6yddQxE2PlerET0Uhy8ASbJ36hO68PD3JM=

​
Step 2: Inspect the response

A successful authentication returns: 
{
  "success": true,
  "token": "oauth_ZH5YQZp1mN987w0fI6HfONisbrF1GX3wujdjIQRT4Eo7rSq7ZbE0GfGyjIw0vOUP",
  "token_type": "Bearer",
  "expires_in": 3600,
  "message": "Authentication successful"
}

​
Step 3: Use the token

Important: all API requests (except /auth) must include the following headers:
# Example: listing products via the integrations base URL
curl -X GET "https://integrations.clopos.com/open-api/products" \
  -H "x-token: oauth_ZH5YQZp1mN987w0fI6HfONisbrF1GX3wujdjIQRT4Eo7rSq7ZbE0GfGyjIw0vOUP" \
  -H "x-brand: openapitest" \
  -H "x-venue: 1"
Required headers:
  • x-token: Access token from the auth response
  • x-brand: Brand identifier (for example openapitest)
  • x-venue: Venue ID (for example 1)
Optional headers:
  • x-stage: Environment stage, if applicable

​
Token management

Tokens are valid for 1 hour (3600 seconds). Refresh them before they expire to avoid authentication failures.

​
Token expiration

  • Tokens expire after one hour.
  • Once expired, API requests return authentication errors.
  • Implement refresh logic in your application.

​
Best practices

  1. Store tokens securely — never expose them in client-side code.
  2. Implement refresh logic — renew tokens automatically before expiry.
  3. Handle errors gracefully — catch authentication failures and re-authenticate.
  4. Use HTTPS only — never send credentials over unencrypted connections.

​
Error handling

Common authentication errors:
ErrorDescriptionSolution
401 UnauthorizedInvalid or expired tokenRe-authenticate to obtain a new token
400 Bad RequestInvalid credentialsVerify client_id, client_secret, brand, and venue_id
403 ForbiddenInsufficient permissionsContact support to confirm your access scope

​
Code examples

async function authenticate() {
  const response = await fetch('https://integrations.clopos.com/open-api/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      client_id: '{{client_id}}',
      client_secret: '{{client_secret}}',
      brand: '{{brand}}',
      venue_id: '{{venue_id}}'
    })
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error('Authentication failed');
  }

  localStorage.setItem('token', data.token);
  localStorage.setItem('brand', '{{brand}}');
  localStorage.setItem('venue_id', '{{venue_id}}');

  return data.token;
}

async function makeAuthenticatedRequest(url, options = {}) {
  const token = localStorage.getItem('token');
  const brand = localStorage.getItem('brand');
  const venueId = localStorage.getItem('venue_id');

  return fetch(url, {
    ...options,
    headers: {
      'x-token': token,
      'x-brand': brand,
      'x-venue': venueId,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
}

​
Next steps

Once you have your authentication token you can start making API requests: