Authentication

The ShipRules AI REST API uses API keys for authentication. Each key is tied to a specific shop and has a permission level.

Creating an API key

1. Go to Settings > API Keys in the ShipRules AI dashboard.
2. Click “Create API Key”.
3. Enter a label (e.g., “Production”, “Staging”, “CI/CD”).
4. Choose a permission level:
   • Read — can read rules, methods, zones, groups, versions, and simulate rates.
   • Write — everything Read can do, plus create, update, and delete entities.
   • Admin — everything Write can do, plus manage API keys and billing settings.
5. Click “Create”.
6. Copy the key immediately. It’s shown only once. The key starts with sr_live_ followed by 32 hex characters.

Caution

The raw API key is shown only once when you create it. ShipRules AI stores only a bcrypt hash — we cannot recover the key if you lose it. If you lose a key, revoke it and create a new one.

Using the key

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

Authorization: Bearer sr_live_a1b2c3d4e5f6...

Permission levels

Permission	Read	Write	Delete	Manage Keys
Read	Yes	No	No	No
Write	Yes	Yes	Yes	No
Admin	Yes	Yes	Yes	Yes

API key limits by plan

Plan	API Keys	API Access
Starter	0	No API access
Pro	2	Yes
Enterprise	10	Yes

Revoking a key

Go to Settings > API Keys, find the key by its label and prefix (first 8 characters), and click “Revoke”. The key is immediately disabled — any requests using it will return a 401 error.

Error responses

All API errors return a consistent JSON format:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Common authentication errors:

Status	Code	Meaning
401	UNAUTHORIZED	Missing, invalid, or revoked API key
403	FORBIDDEN	Key doesn’t have the required permission level
429	RATE_LIMITED	Too many requests — slow down