Authentication Setup

To access the Gateway API, you need to obtain an access token using OAuth2. This guide walks you through the authentication setup process.

Prerequisites

Before you begin, you’ll need:

Gateway instance URL (<GATEWAY_URL>)
OAuth2 client credentials (client_id and client_secret)
User credentials (for password grant) OR just client credentials (for client credentials grant)

Step 1: Choose Your Authentication Method

The Gateway supports three authentication methods:

Method 1: Client Credentials Grant (Recommended for Apps)

Best for: Server-to-server integrations, background jobs, app-level operations

Pros:

No user context required
Simple to implement
Suitable for automation

Endpoint Access: /api/2.0/app/*

Method 2: Password Grant (User-based)

Best for: User-specific operations, web applications with user login

Pros:

User-scoped access
Supports refresh tokens
Fine-grained permissions

Endpoint Access: /api/1.0/*, /api/2.0/user/*

Method 3: Account-based (Web Components)

Best for: Embedded widgets, account-scoped operations

Endpoint Access: /api/2.0/webcomponent/*

Step 2: Obtain Access Token

Option A: Client Credentials Grant

Request:

curl -X POST https://<GATEWAY_URL>/oauth/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scope": "*"
  }'

Response:

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoi..."
}

Option B: Password Grant

Request:

curl -X POST https://<GATEWAY_URL>/oauth/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "username": "[email protected]",
    "password": "your-password",
    "scope": "*"
  }'

Response:

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200..."
}

Step 3: Store Your Token Securely

[!CAUTION] Never commit access tokens to version control or expose them in client-side code!

Best Practices:

Use Environment Variables:

# .env file
GATEWAY_ACCESS_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
GATEWAY_CLIENT_ID=your-client-id
GATEWAY_CLIENT_SECRET=your-client-secret

Encrypt at Rest: Use encryption for stored tokens in databases:

// Laravel example
$encrypted = encrypt($accessToken);

Use Secure Storage:

Server-side: Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
Client-side: Use secure session storage (never localStorage for tokens)

Step 4: Test Your Authentication

Verify your token works by making a test request:

curl -X GET https://<GATEWAY_URL>/api/2.0/app/services \
  -H "Authorization: Bearer your-access-token" \
  -H "Accept: application/json"

Expected Response:

{
  "data": [
    {
      "id": 1,
      "name": "Shopify",
      "type": "SHOPIFYV2",
      "logo": "https://..."
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 10
  }
}

Refreshing Tokens

When to Refresh

Tokens expire after 1 year (31,536,000 seconds). Refresh your token when:

You receive a 401 Unauthorized response
The token is close to expiration (check expires_in field)

Refresh Token Flow (Password Grant Only)

curl -X POST https://<GATEWAY_URL>/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your-refresh-token",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scope": "*"
  }'

Response:

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "new-access-token",
  "refresh_token": "new-refresh-token"
}

[!IMPORTANT] Client Credentials Grant does NOT support refresh tokens. Simply request a new token when needed.

Handling Authentication Errors

401 Unauthorized

Cause: Invalid or expired token

Solution:

Refresh the token (if using password grant)
Request a new token (if using client credentials)

400 Bad Request

Cause: Invalid credentials or malformed request

Example Error:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed",
  "message": "Client authentication failed"
}

Solution:

Verify client_id and client_secret are correct
Check request payload format
Ensure Content-Type: application/json header is set

Code Examples

PHP (Laravel/Guzzle)

use Illuminate\Support\Facades\Http;

$response = Http::post('https://<GATEWAY_URL>/oauth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => env('GATEWAY_CLIENT_ID'),
    'client_secret' => env('GATEWAY_CLIENT_SECRET'),
    'scope' => '*'
]);

$accessToken = $response->json()['access_token'];

// Use the token
$integrations = Http::withToken($accessToken)
    ->get('https://<GATEWAY_URL>/api/2.0/app/integrations')
    ->json();

JavaScript (Node.js)

const axios = require('axios');

async function getAccessToken() {
  const response = await axios.post('https://<GATEWAY_URL>/oauth/token', {
    grant_type: 'client_credentials',
    client_id: process.env.GATEWAY_CLIENT_ID,
    client_secret: process.env.GATEWAY_CLIENT_SECRET,
    scope: '*'
  });

  return response.data.access_token;
}

async function getIntegrations() {
  const token = await getAccessToken();

  const response = await axios.get('https://<GATEWAY_URL>/api/2.0/app/integrations', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  return response.data;
}

Python

import requests
import os

def get_access_token():
    response = requests.post(
        'https://<GATEWAY_URL>/oauth/token',
        json={
            'grant_type': 'client_credentials',
            'client_id': os.getenv('GATEWAY_CLIENT_ID'),
            'client_secret': os.getenv('GATEWAY_CLIENT_SECRET'),
            'scope': '*'
        }
    )
    return response.json()['access_token']

def get_integrations():
    token = get_access_token()
    response = requests.get(
        'https://<GATEWAY_URL>/api/2.0/app/integrations',
        headers={'Authorization': f'Bearer {token}'}
    )
    return response.json()

Next Steps

Now that you’re authenticated: