Authentication

Getting Your API Keys

API keys are managed from your Gridline dashboard. Each key is scoped to a specific environment and merchant.

1. Navigate to Dashboard > Settings > API Keys
2. Click Generate New Key
3. Choose an environment: Sandbox or Production
4. Set the permissions scope for the key
5. Copy the key immediately (it will not be shown again)

Bearer Token Format

Include your API key in the Authorization header of every request:

Authorization: Bearer sk_live_your_api_key_here

API keys are prefixed by environment: sk_live_ for production and sk_test_ for sandbox.

JWT Token Structure

For user-scoped access (e.g., mobile apps), Gridline issues short-lived JWT tokens via the OAuth flow. The token payload contains:

{
  "sub": "usr_abc123",
  "merchant_id": "mer_xyz789",
  "role": "admin",
  "permissions": ["orders:read", "orders:write", "products:read"],
  "iat": 1700000000,
  "exp": 1700003600,
  "iss": "https://auth.gridlinepos.com"
}

• sub — The user ID
• merchant_id — The merchant this token is scoped to
• role — User role (admin, manager, cashier)
• exp — Token expiration (1 hour by default)

Token Refresh Flow

Access tokens expire after 1 hour. Use a refresh token to obtain a new access token without re-authenticating:

{
  "refresh_token": "rt_your_refresh_token_here"
}

Response includes a new access token and refresh token. The old refresh token is invalidated (rotation).

Code Examples

curl -X GET https://api.gridlinepos.com/v1/orders \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

import { Gridline } from '@gridline/sdk';

const client = new Gridline({
  apiKey: process.env.GRIDLINE_API_KEY,
});

// The SDK handles auth headers automatically
const orders = await client.orders.list({ limit: 10 });

import gridline
import os

client = gridline.Client(api_key=os.environ["GRIDLINE_API_KEY"])

# The SDK handles auth headers automatically
orders = client.orders.list(limit=10)