Create organization API keys

An organization API key lets your own systems call the Commerce API, the email marketing API and the game network feed without a person signing in. The key belongs to one organization. Its scopes say what it may do, and you can cap how many requests it makes and where they come from.

A key works on the Commerce API, at https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/..., on the email marketing API, at https://api.coritan.com/api/v1/orgs/{org_slug}/marketing/..., and on the game network feed, at https://api.coritan.com/api/v1/orgs/{org_slug}/network/..., sent in the X-API-Key header. A key with the commerce.storefront:forward scope also works on the Store API routes where a storefront's server passes on its visitors' addresses. Every other organization route takes a member's access token instead.

• You need the owner or admin role in the organization. The API keys page is not in the menu for other roles.
• For the Commerce API, Commerce must be turned on for the organization. Coritan turns it on, so ask support if it is not. Until then, the API keys page says Commerce is not on for this organization, and every Commerce API route answers 404 with the message Commerce is not enabled for this organization. The game network feed works without Commerce.
• Work out which scopes the key needs from the table below. Give it the fewest that do the job.

A key reaches nothing until you give it scopes. A :write scope includes the :read scope of the same area.

Two wider forms exist. commerce:* grants every scope, the email marketing and game network scopes included, and an area with :*, such as commerce.orders:* or network:*, grants every scope in that area. marketing:* grants every email marketing scope. The marketing.campaigns:send scope is not part of marketing.campaigns:write: a key needs it by name. No key can manage the merchant profile, because it holds the owners' identities: an admin does that signed in. No key can ask for a payout either: an admin asks for one signed in.

1. Go to Organizations, open your organization, then choose Settings, then API keys. In the sidebar, you find them in your organization's block, under Settings.
2. Choose New key….
3. Enter a Label of at least two characters that says what the key is for. The label is the only way to tell keys apart later.
4. Under Scopes, tick the scopes the key needs, such as Read orders, or Update the game network for the program that runs your game network. Each one shows its scope name, such as commerce.orders:read, from the table above. Tick Every scope instead to grant commerce:*, which includes the scopes added later. You cannot change the scopes once the key exists. The email marketing scopes, such as Read contacts and Send campaigns, are in the same list, and Every scope grants them too.
5. Choose a Rate limit. The default is 4,000 requests an hour.
6. Optionally, fill in the IP allow-list with the addresses or CIDR ranges the key may be used from, such as 203.0.113.0/24. Separate them with commas or new lines. We refuse requests from anywhere else.
7. Choose Create key. The dialog API key created shows the key, which starts with ct_, with its scopes and limits. Copy the key, then choose I have saved them. We show it once and cannot show it again.

Send the key in the X-API-Key header, as Call the Commerce API with the key shows.

1. On the API keys page, choose Revoke… on the key's row.
2. Type revoke and choose Revoke key.

The key stays in the table marked Revoked. You cannot turn it back on, so create a new key to replace it. Requests with the key can succeed for up to 10 seconds after you revoke it.

The table lists every key with its Status, its Scopes (Every scope, or how many it has), its Rate limit and the addresses it is Allowed from, or Anywhere when it has no allow-list. A key with none, such as one created through the API without permissions, shows No scopes: it reaches nothing, so replace it. The Last used column shows Never for every key, because we do not record when a key is used yet. A key never appears in full again after the creation dialog closes.

401 Missing API key or 401 Invalid API key

The request had no X-API-Key header, or the key is wrong or revoked. A key sent as Authorization: Bearer is not read at all.

403 API key is not allowed from this address

The request came from an address outside the key's allow-list.

403 with scope_required

The key lacks the scope the route needs. The message names it, for example This API key needs the commerce.orders:read scope. Scopes cannot be changed on an existing key, so create a new key with the scopes it needs and revoke the old one.

403 with people_only

The route manages the merchant profile, which no key can reach. An admin has to do it signed in.

403 Organization inactive

The organization is not active: it is pending, suspended, closed or deleted. Its keys work again only if it becomes active.

404 Organization not found

The organization slug in the path is not the one the key belongs to.

429 API key rate limit exceeded

The key made more requests in the last 60 minutes than its rate limit allows. Wait, or create a key with a higher limit.

• Sell with the Commerce API
• Set up email marketing for your store
• Connect your game network to your storefront
• Roles and permissions
• Organization settings

Managing keys takes an owner's or admin's access token, sent as Authorization: Bearer $CORITAN_TOKEN.

Send the scopes as a list under permissions.scopes:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/api-keys" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Order sync", "permissions": {"scopes": ["commerce.orders:read", "commerce.fulfillment:write"]}, "rate_limit_per_hour": 4000, "ip_whitelist": ["203.0.113.0/24"]}'

For the email marketing API, send the marketing.* scopes the same way. A key that reads contacts and sends campaigns holds ["marketing.contacts:read", "marketing.campaigns:write", "marketing.campaigns:send"].

The answer is 201 with the key's id, label, permissions, rate_limit_per_hour, ip_whitelist, is_active and created_at, and the key itself in raw_key. Store raw_key now: no later answer contains it.

curl "https://api.coritan.com/api/v1/orgs/acme/commerce/orders?limit=20" \
  -H "X-API-Key: $ORG_API_KEY"

The game network feed takes the key the same way. Connect your game network to your storefront shows its requests.

No route changes a key once it exists.