Authentication

The Cresva API uses bearer tokens to authenticate requests. This guide covers how to create tokens, assign scopes, and keep your credentials secure.

Auth surface preview

The Storefront API uses Bearer tokens today. Token issuance UX, scope catalog, and management endpoints described here ship with the public Management API release.

Base URL

The live Storefront API base URL is:

text

https://api.cresva.ai/api/storefront/[brandId]/

The unauthenticated discovery manifest is at:

text

https://api.cresva.ai/.well-known/acp.json

Token format

API tokens are prefixed with cresva_ak_ followed by 32 hexadecimal characters. For example:

text

cresva_ak_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Creating tokens

To create an API token, navigate to Dashboard → Configure → Developer → Apps in the Cresva dashboard. From there you can generate a new token and assign the scopes it requires.

Your token is only shown once at the time of creation. Cresva stores tokens as a SHA-256 hash, so it cannot be retrieved later. Copy and store it in a secure location immediately.

API Scopes

Scopes control what resources a token can access. Assign only the scopes your integration needs.

products:readRead product catalog data

products:writeCreate, update, and delete products

queries:readRead agent query logs

transactions:readRead transaction history

transactions:writeRecord external transactions

trust:readRead trust scores and history

analytics:readRead analytics and reporting data

verticals:readRead vertical profiles and attributes

deployments:readRead deployment configurations

deployments:writeCreate and update deployments

webhooks:manageCreate, update, and delete webhook endpoints

Use wildcard scopes like products:* to grant both read and write access for a resource.

Using your token

Pass your token in the Authorization header as a Bearer token.

bash

curl https://api.cresva.ai/api/storefront/[brandId]/products \
  -H "Authorization: Bearer cresva_ak_a1b2c3d4e5f6..."

javascript

const response = await fetch("https://api.cresva.ai/api/storefront/[brandId]/products", {
  headers: {
    Authorization: "Bearer " + process.env.CRESVA_API_KEY,
  },
});

const { data } = await response.json();

Security best practices

Never share your API tokens in public repositories, client-side code, or chat messages.
Store tokens in environment variables rather than hard-coding them in source files.
Rotate your tokens regularly to limit the impact of any potential leak.
Use the minimum required scopes for each token so a compromised token has limited access.
Revoke compromised tokens immediately from the dashboard and generate a replacement.