Skip to content
cresvaDevelopers

Authentication

There are three levels of access: none, a public key, and a secret key. Most of the Storefront API needs no credential at all.

No key

Discovery, catalogue reads, search, compare and trust all answer without a credential. An anonymous caller is identified by source address and limited to 10 requests per minute.

bash
curl "https://cresva.ai/api/storefront/$BRAND_ID/products?limit=2"

This is not a trial tier or a courtesy. A shopping agent that has just discovered a storefront holds no credential for it, so an OSP storefront that demanded one before it would say what it sells could never be found by the agents it exists to serve.

The two key types

pk_live_publicRead and discovery traffic from a named agent. 60 requests per minute. Safe in a place a public key can be read, which is what it is for.
sk_live_secretServer side only, and the only kind allowed to open a checkout session or move an order forward. 300 requests per minute.
pk_test_ / sk_test_testThe same two types against test data.

There are no scopes. A key has a type and a brand, and that is the whole model. There is nothing resembling products:read to request, grant or forget to grant: what a key may do follows entirely from which of the two types it is.

Key format

A prefix naming the type, followed by 48 hexadecimal characters from 24 random bytes.

text
pk_live_1f0c9a7b3e5d2c48a6b1e09f7d4c3b2a18e6f5d4c3b2a1908
sk_live_7d4c3b2a18e6f5d4c3b2a19081f0c9a7b3e5d2c48a6b1e09f

A key is shown once, when it is created. Cresva stores only a SHA-256 hash of it, so it cannot be recovered later. Copy it then or generate a new one.

Sending a key

As a bearer token.

bash
curl "https://cresva.ai/api/storefront/$BRAND_ID/products" \
  -H "Authorization: Bearer $CRESVA_PUBLIC_KEY"

An api_key query parameter is also accepted and should be avoided: it lands in access logs, proxy logs and browser history in a way a header does not.

How a key is refused

401 unauthorizedinvalidThe key does not match any active key.
403 forbiddenwrong brandThe key is valid but belongs to a different brand than the one in the URL. Keys are scoped to one brand and do not travel.
429 rate_limitedover the limitWith a Retry-After header.
503limiter unreachableWe could not enforce a limit, so we did not serve the request. Deliberately not a 429: the fault is ours.

Two origins, and they are not interchangeable

https://cresva.ai/api/storefront/{brandId}/storefrontEvery storefront route. This is the origin an agent talks to.
https://api.cresva.ai/.well-known/osp.jsondiscoveryThe discovery manifest. Also served from cresva.ai.

api.cresva.ai serves the .well-known documents and the /v1 platform API. It returns 404 for /api/storefront/*. If you are getting a 404 on a storefront path that you believe exists, check the host first.

Keeping a key safe

  • A secret key never reaches a browser. It is the only credential that can open a checkout session.
  • Store keys in environment variables, not in source. The repository is where a leaked key usually starts.
  • Use a public key when a public key is enough, which is most of the time.
  • Revoke a compromised key from the dashboard and generate a replacement. A revoked key stops authenticating immediately.