Get a key

1. The store asks for access

The API is part of Stockroom's paid advanced tier. Purchase orders and receiving are free and stay free; programmatic access is the advanced end of the product, and while it is in early access it is available on request rather than switched on for everyone.

In Stockroom, the merchant goes to Settings, then API, and clicks Request access. We turn it on for that store by hand. Until then the page shows the date they asked, and the API answers every request with402 feature_not_enabled.

2. Someone creates a key

Once access is on, Settings then API holds the key list.Create key asks for three things:

• Name. What is using it. One key per integration, so revoking one does not break the others, and so the store's activity log tells you which system made a call.
• Scopes. What the key may change. Every key can read. See Authentication and scopes for what each write scope covers.
• Expires. Never, in 90 days, or in 1 year.

Stockroom shows the key once, at creation. It stores only a hash, so nobody - including us - can read it back. If it goes missing, the merchant revokes that key and creates another.

A key looks like srk2_ followed by a long random string. Its first thirteen characters are shown in the key list as the prefix, which is how a merchant matches a key in the list to the one your system holds without either of you handling the secret.

Keep the key out of your repository

A Stockroom key can place orders and move stock in a real store. Treat it the way you would treat a payment provider's secret key: an environment variable or a secret manager, never a committed file, never a front-end bundle, never a URL query string. Every call is server to server - there is no browser-safe public key, and the API sends no CORS headers, so a key in front-end JavaScript would not work even if you wanted it there.

What a merchant can see and do

• Revoke. Immediate and permanent: the next request with that key is a401. The row stays in the list so the history still reads.
• Last used. When the key last made a call, and from what address.
• Recent activity. The last requests each key made, with the endpoint, the result and how long it took. This is the first place to look when something is not working, and it is worth asking the merchant for a screenshot of it before you start guessing.

A store can have twenty active keys at once. Expired and revoked keys do not count against that.

Prove the key works

curl -i https://api.stockroom.app/v2/whoami \
  -H "Authorization: Bearer srk2_your_key_here"