OAuth 2.0 Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

CHEQI_CLIENT_ID=your_client_id
CHEQI_CLIENT_SECRET=your_client_secret  # Store securely!
CHEQI_REDIRECT_URI=https://yourapp.com/oauth/callback

GET https://api.cheqi.io/oauth2/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/oauth/callback&
  scope=read_receipts write_receipts&
  state=random_state_string

// Construct authorization URL
const url = "https://api.cheqi.io/oauth2/authorize";
const params = {
  client_id: "your_client_id",
  redirect_uri: "https://yourapp.com/oauth/callback",
  scope: "read_receipts write_receipts",
  state: generateRandomState()  // CSRF protection
};

// Redirect user to authorization URL
redirect(url + "?" + buildQueryString(params));

https://yourapp.com/oauth/callback?code=AUTH_CODE&state=RANDOM_STATE

// Handle OAuth callback
function handleOAuthCallback(request) {
  const code = request.query.code;
  const state = request.query.state;
  
  // Verify state to prevent CSRF
  if (state !== session.oauthState) {
    return error("Invalid state parameter");
  }
  
  // Exchange code for tokens (see next step)
  const tokens = await exchangeCodeForTokens(code);
  
  // Store tokens securely in your database
  await saveTokens(tokens);
  
  redirect("/dashboard");
}

curl -X POST https://api.cheqi.io/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'

[
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "rt_1234567890abcdef1234567890abcdef",
    "token_type": "AUTHORIZATION_CODE",
    "expires_at": "2024-01-13T23:00:00Z",
    "refresh_expires_at": "2024-02-13T22:00:00Z",
    "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
    "tax_id": "NL123456789B01",
    "company_legal_name": "Example Coffee Shop B.V.",
    "customer_id": null
  }
]

curl https://api.cheqi.io/receipt/template \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{...}'

// Initialize SDK without API key
CheqiSdk sdk = new CheqiSdkBuilder()
    .environment(Environment.PRODUCTION)
    .build();

// Use access token for each request
ReceiptResult result = sdk.getReceiptService().sendReceipt(
    identificationDetails,
    receiptRequest,
    accessToken  // Pass token here
);

curl -X POST https://api.cheqi.io/oauth2/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_9876543210fedcba9876543210fedcba",
  "token_type": "AUTHORIZATION_CODE",
  "expires_at": "2024-01-13T23:00:00Z",
  "refresh_expires_at": "2024-02-13T22:00:00Z",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
  "tax_id": "NL123456789B01",
  "company_legal_name": "Example Coffee Shop B.V.",
  "customer_id": null
}

class TokenManager {
  async getValidToken(companyId) {
    const tokens = await loadTokens(companyId);
    
    // Check if token expires in next 5 minutes
    if (this.isExpiringSoon(tokens.expires_at)) {
      return await this.refreshToken(tokens.refresh_token);
    }
    
    return tokens.access_token;
  }
  
  isExpiringSoon(expiresAt) {
    const fiveMinutes = 5 * 60 * 1000;  // 5 minutes in milliseconds
    return Date.now() + fiveMinutes >= new Date(expiresAt).getTime();
  }
  
  async refreshToken(refreshToken) {
    const response = await fetch('https://api.cheqi.io/oauth2/refresh', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'refresh_token',
        refresh_token: refreshToken,
        client_id: process.env.CHEQI_CLIENT_ID,
        client_secret: process.env.CHEQI_CLIENT_SECRET
      })
    });
    
    const tokens = await response.json();
    await this.saveTokens(tokens);
    return tokens.access_token;
  }
}

// Company-level access (POS system)
const scope = "write_receipts read_stores";
// Merchant selects which companies to authorize

// Identifier access (expense tracker)
const scope = "read_receipts account_access";
// Merchant selects which identifiers to authorize (cards, payment accounts, emails)

// ❌ BAD - Client secret in frontend
const clientSecret = 'your_client_secret';

// ✅ GOOD - Client secret on backend only
const clientSecret = process.env.CHEQI_CLIENT_SECRET;

// Generate random state before redirect
const state = crypto.randomBytes(32).toString('hex');
req.session.oauthState = state;

// Verify state in callback
if (req.query.state !== req.session.oauthState) {
  throw new Error('Invalid state parameter');
}

// Encrypt before storing
const encryptedToken = encrypt(accessToken, encryptionKey);
await db.tokens.create({
  companyId,
  accessToken: encryptedToken,
  expiresAt: Date.now() + (expiresIn * 1000)
});

async function makeAuthenticatedRequest(url, options) {
  let token = await getValidToken();
  
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${token}`
    }
  });
  
  // If 401, refresh and retry once
  if (response.status === 401) {
    token = await refreshToken();
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`
      }
    });
  }
  
  return response;
}

// Token exchange returns array of tokens
const tokens = await exchangeCodeForTokens(code);

// Store tokens per company
for (const token of tokens) {
  await saveTokens(token.merchant_id, {
    access_token: token.access_token,
    refresh_token: token.refresh_token,
    expires_at: new Date(token.expires_at).getTime(),
    scope: token.scope
  });
}

// Use appropriate token for each company
const token = await getTokenForCompany(companyId);

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired",
  "timestamp": "2024-01-13T21:00:00Z"
}

const authUrl = new URL('https://sandbox.api.cheqi.io/oauth2/authorize');
authUrl.searchParams.append('client_id', 'sandbox_client_id');
authUrl.searchParams.append('redirect_uri', 'http://localhost:3000/callback');
authUrl.searchParams.append('scope', 'read_receipts write_receipts');

curl https://api.cheqi.io/oauth2/token/validate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

true