Authentication

All SkyTab POS API requests require HMAC-SHA256 signature authentication. Each request must be cryptographically signed using your client credentials, with signatures valid for only 10 seconds. This ensures secure communication and prevents replay attacks.

Required Headers

Every authenticated API request must include three special HTTP headers:

Header	Description
`x-access-key`	Your public client identifier (CLIENT_ID)
`x-timestamp`	Current Unix time in seconds
`x-signature`	The computed HMAC-SHA256 signature

All requests must use HTTPS—plain HTTP calls will fail. Obtain your client credentials (CLIENT_ID and CLIENT_SECRET) from the Shift4 developer console.

Example authenticated request

curl -X GET \
  'https://conecto-api.shift4payments.com/api/v1/export/244/tickets' \
  -H 'x-access-key: 23b08412a29bbe8625967e16c1a41dc9' \
  -H 'x-timestamp: 1709251200' \
  -H 'x-signature: 01be9d576867309aba8c29e7b6a719fa7607bdfd26177bfd4ce453450c610126'

Important: Every signature has a limited lifetime of 10 seconds. Ensure your server time is synchronized via NTP or another precise time source to prevent authentication failures.

Signature Generation

The HMAC-SHA256 signature is constructed from five concatenated components in this exact order:

CLIENT_ID - Your public client identifier
Request Method - HTTP method in uppercase (GET, POST, PATCH, etc.)
Request Path - URI path in lowercase, excluding host and query parameters
Request Body - Empty string if no body exists
Unix Timestamp - Current time in seconds

These components are concatenated without separators, then hashed using HMAC-SHA256 with your CLIENT_SECRET, producing a hexadecimal digest.

JavaScript Example

Generate HMAC signature

const crypto = require('crypto');

const CLIENT_ID = '23b08412a29bbe8625967e16c1a41dc9';
const CLIENT_SECRET = 'de17f1f0-4816-157b-97ae-eb4b0f656a1f';

// Current Unix timestamp
const timestamp = Math.floor(Date.now() / 1000);

// Request details
const method = 'GET';
const path = '/api/v1/export/1/tickets';
const body = ''; // Empty for GET requests

// Concatenate components
const message = CLIENT_ID + method + path + body + timestamp;

// Generate HMAC-SHA256 signature
const signature = crypto
  .createHmac('sha256', CLIENT_SECRET)
  .update(message)
  .digest('hex');

console.log('x-access-key:', CLIENT_ID);
console.log('x-timestamp:', timestamp);
console.log('x-signature:', signature);

Python Example

Generate HMAC signature in Python

import hmac
import hashlib
import time

CLIENT_ID = '23b08412a29bbe8625967e16c1a41dc9'
CLIENT_SECRET = 'de17f1f0-4816-157b-97ae-eb4b0f656a1f'

# Current Unix timestamp
timestamp = str(int(time.time()))

# Request details
method = 'GET'
path = '/api/v1/export/1/tickets'
body = ''  # Empty for GET requests

# Concatenate components
message = CLIENT_ID + method + path + body + timestamp

# Generate HMAC-SHA256 signature
signature = hmac.new(
    CLIENT_SECRET.encode('utf-8'),
    message.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(f'x-access-key: {CLIENT_ID}')
print(f'x-timestamp: {timestamp}')
print(f'x-signature: {signature}')

Security Best Practices

Protect Your Credentials

Never commit CLIENT_SECRET to version control
Store credentials in environment variables or secure vaults
Use different credentials for development and production
Rotate credentials periodically

Time Synchronization

Since signatures expire after 10 seconds, precise time synchronization is critical:

Use NTP (Network Time Protocol) to synchronize server clocks
Monitor time drift and adjust if necessary
Handle authentication errors gracefully with retry logic

Request Path Formatting

The request path used in signature generation must be:

Lowercase - Convert the entire path to lowercase
Path only - Exclude the host and query parameters
No trailing slashes - Remove any trailing slashes

Example: https://conecto-api.shift4payments.com/api/v1/export/1/tickets?filter=value becomes /api/v1/export/1/tickets for signature generation.

Testing Authentication

Use Postman or curl to test your authentication implementation:

Test authentication with curl

#!/bin/bash

CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
TIMESTAMP=$(date +%s)
METHOD="GET"
PATH="/api/v1/export/1/tickets"
BODY=""

MESSAGE="${CLIENT_ID}${METHOD}${PATH}${BODY}${TIMESTAMP}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" | cut -d' ' -f2)

curl -X GET \
  "https://conecto-api.shift4payments.com${PATH}" \
  -H "x-access-key: ${CLIENT_ID}" \
  -H "x-timestamp: ${TIMESTAMP}" \
  -H "x-signature: ${SIGNATURE}"