Authentication

Authenticate with the YNS API using API keys and the Commerce SDK.

API Keys

All YNS API requests require authentication via an API key. You can create and manage keys in the YNS dashboard under Settings → API → API keys.

Key Types

Prefix	Environment	Endpoint
`sk-`	Production	`yns.store`
`sk-s-`	Staging	`yns.cx`

Staging keys connect to a sandbox environment where you can test without affecting real data or processing real payments.

SDK Authentication

The Commerce SDK handles authentication automatically:

import { Commerce } from "commerce-kit";

// Reads YNS_API_KEY from environment
const commerce = Commerce();

// Or pass explicitly
const commerce = Commerce({
  token: "sk-your-api-key",
});

The SDK adds the API key to every request as a Bearer token in the Authorization header.

Direct API Authentication

If you're calling the API directly (without the SDK), include the key in the Authorization header:

curl https://yns.store/api/v1/products \
  -H "Authorization: Bearer sk-your-api-key"

API Key Scopes

Each API key can be scoped to a set of capabilities that control which endpoints it can access. Scopes are selected when you create a key in the dashboard.

Available Scopes

Scope	Description
`storefront:read`	Read the public catalog, content, and checkout settings a storefront renders
`storefront:write`	Accept visitor submissions: contact form, newsletter signup, reviews, comments
`cart:write`	Create and modify carts
`order:lookup`	Read a single order by ID (order-confirmation page)
`catalog:write`	Create and edit products, variants, categories, collections, brands, inventory
`content:read`	Read the review queue, comment queue, and media library
`content:write`	Edit posts, blog categories, legal pages, media, brand kit, and socials
`orders:read`	List and read all orders, refunds, and shipments
`orders:write`	Update orders, issue refunds, create shipments
`customers:read`	List and read customers and their order history
`customers:write`	Edit customers and their addresses
`marketing:read`	Read coupons, promotions, newsletters, subscribers, and loyalty
`marketing:write`	Manage coupons, promotions, loyalty, and send newsletters
`messages:read`	Read the inbox and support cases
`messages:write`	Reply to customers and manage support cases
`events:read`	Read events, attendees, and check-ins
`events:write`	Manage events, tickets, and check-ins
`analytics:read`	Read sales and overview analytics
`settings:read`	Read store settings and connected addons
`settings:write`	Change store settings and addon configuration
`team:read`	List team members and invitations
`team:write`	Invite members, change roles, transfer ownership
`store:admin`	Reset the catalog, manage the domain, publish the store
`ai:write`	Generate images, spending store credits

Storefront Keys

When you create a key for a deployed storefront (the YNS_API_KEY your store template uses), select only the storefront preset: storefront:read, storefront:write, cart:write, and order:lookup. This limits what a leaked storefront key can do — it cannot read customer PII, enumerate orders, or modify store settings.

Backward Compatibility

Keys created before scopes were introduced have no scope restrictions and continue to work on all endpoints. Only newly minted keys are constrained to their declared scopes.

Scope Errors

If a key is missing the scope required by an endpoint, the API returns 403 with a message indicating which scope is needed:

{
  "error": "This API key is missing the 'catalog:write' scope",
  "hint": "Mint a key that includes 'catalog:write', or use one with broader capabilities."
}

Security Best Practices

Never expose API keys in client-side code. The SDK is designed for server-side use only (Server Components, Server Actions, API routes).
Use staging keys for development. Switch to production keys only in your deployed environment.
Rotate keys if compromised. You can create new keys and revoke old ones from the dashboard.
Use environment variables. Store keys in .env.local (local) or your hosting platform's environment variable settings (production).
Use the narrowest scopes possible. A storefront key should only have storefront:read, storefront:write, cart:write, and order:lookup. Admin keys used by integrations should only include the scopes they actually need.

PreviousOverviewCommerce SDK NextProductsCommerce SDK