API Keys

The API Keys page manages authentication keys for external tools that push data into the middleware via the External Orders API.

Overview

Navigate to GSM Middleware → API Keys to manage keys.

Each API key is scoped to a single site and grants permission to submit orders via the REST API. Keys are generated with a secure random value, hashed with SHA-256 for storage, and the plaintext is shown only once at creation.

Key Features:

• Per-site API key scoping
• SHA-256 hashed storage (plaintext never stored)
• One-time key reveal with copy-to-clipboard
• Immediate, permanent revocation
• Last-used tracking for auditing

Permission Required: manage_options

Interface

Key Table

The main table displays all API keys:

Column	Description
Prefix	First 12 characters of the key for identification
Label	Human-readable description (e.g., "Production POS Integration")
Site	The site this key is authorized for
Last Used	Timestamp of most recent API call
Created	When the key was generated
Status	Active (green) or Revoked (red) badge
Actions	Revoke button (active keys only)

Generating a New Key

1. Click Generate New Key
2. Select the Site from the dropdown
3. Enter a Label (descriptive name for the key's purpose)
4. Click Generate
5. The plaintext key appears in a reveal modal

warning

Copy the key immediately! The full key is shown only once. After closing the modal, only the 12-character prefix is visible. If you lose the key, you must revoke it and generate a new one.

Key Format

Keys are used as Bearer tokens in API requests:

Authorization: Bearer gsm_k_abc123def456...

Revoking a Key

1. Click Revoke on the key row
2. Confirm the revocation dialog
3. The key is immediately and permanently disabled

Revoked keys cannot be reactivated. Generate a new key if access is needed again.

Security Model

Storage

• Keys are hashed with SHA-256 before database storage
• The rm_api_keys table stores only the hash and metadata
• A 12-character prefix is stored separately for identification
• No mechanism exists to recover the original plaintext

Validation

When an API request arrives with a Bearer token:

1. The token is hashed with SHA-256
2. The hash is looked up in rm_api_keys
3. If found and active, the request proceeds with the key's site scope
4. last_used_at is updated for auditing
5. If not found or revoked, HTTP 401 is returned

Rate Limiting

Application-level rate limiting is not implemented. Rate limiting is handled at the infrastructure level (e.g., Imperva WAF).

Database

API keys are stored in the rm_api_keys table in the tasks database:

Column	Type	Description
id	INT	Auto-increment primary key
site_id	INT	Associated site ID
key_hash	VARCHAR(64)	SHA-256 hash of the key
key_prefix	VARCHAR(12)	Visible prefix for identification
label	VARCHAR(255)	Human-readable label
scopes	JSON	Permission scopes
is_active	TINYINT	1 = active, 0 = revoked
last_used_at	DATETIME	Last API call timestamp
created_at	DATETIME	Key creation timestamp

Usage Example

cURL

curl -X POST \
  https://your-site.com/wp-json/gsm-middleware/v1/external/orders \
  -H "Authorization: Bearer gsm_k_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": 1,
    "order_number": "EXT-1001",
    "line_items": [
      {"sku": "PROD-001", "quantity": 2, "price": 29.99}
    ],
    "billing_address": { ... },
    "shipping_address": { ... }
  }'

See External Orders API for the complete API reference.

Related Documentation

• External Orders API — REST API reference for submitting orders
• Settings — Global plugin settings
• Security Best Practices — Credential management guidelines