Working with API Keys

API Keys

Spartera supports two types of API keys, each with a distinct purpose and scope. Understanding the difference is critical to building secure integrations.

Two Key Types at a Glance

	Analytics Key	Endpoint Key
Prefix	`sk_spartera_`	`ep_`
Scope	Company-wide	One specific endpoint
Used by	Sellers (data providers)	Buyers (data consumers)
Capabilities	Full CRUD on assets, endpoints, connections; run analytics; pull data	Fetch data from one endpoint only
Where to use	Internal API routes (`/companies/<cid>/...`)	Customer-facing route (`/endpoints/v1/<slug>`)
How created	Manually via UI/API	Marketplace auto-provision OR seller-minted
Role-gated	✅ (key inherits role from creator, capped at company role)	No (always read-only)

Analytics Keys (`sk_spartera_...`)

Analytics keys are full-access seller credentials. They authenticate you as the data owner and can do everything: create/read/update/delete endpoints and assets, manage connections, run test pulls during setup, and hit the management API.

Treat analytics keys like admin credentials — one per person or service, kept secret.

What an Analytics Key Can Do

Subject to the key's role level (1–5):

Create, read, update, delete assets (calculations, visualizations)
Create, read, update, delete endpoints
Create, read, update, delete database connections
Run analytics assets via /analyze/<company_handle>/assets/<asset_slug>
Fetch data from your own endpoints (no charge — is_company_owned)
Manage other API keys (subject to role)

Role Levels

When you create an analytics key, you assign it a role. The key can do anything that role can do — but no more.

Role	Description
1 — Analyst	Read-only access
2 — Data Scientist	Create and modify analytics
3 — Data Engineer	Manage connections and endpoints
4 — Admin	Full company access
5 — Super Admin	Cross-company access (Spartera staff only)

You can only create keys with a role level at or below your own. So a Data Engineer (3) can mint Analyst (1), Data Scientist (2), and Data Engineer (3) keys, but not Admin keys.

Creating an Analytics Key

Dashboard → Settings → API Keys → Generate New Key

Or via API:

curl -X POST "https://api.spartera.com/companies/{company_id}/api_keys" \
  -H "x-api-key: your-existing-analytics-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CI",
    "role_id": 3,
    "key_type": "analytics",
    "expiration_date_utc": "2026-12-31T23:59:59Z"
  }'

The response includes the plain text key value once. After that, only the masked value is retrievable. Save it immediately.

Using an Analytics Key

curl "https://api.spartera.com/companies/{company_id}/endpoints" \
  -H "x-api-key: sk_spartera_..."

Endpoint Keys (`ep_...`)

Endpoint keys are scoped, single-purpose credentials tied to one specific endpoint. They can only do one thing: fetch data from that endpoint via /endpoints/v1/<slug>.

They cannot read endpoint config, cannot update anything, cannot reach any other endpoint, and cannot be used on internal management routes. Always read-only (role 1).

Two Ways Endpoint Keys Get Created

1. Marketplace Auto-Provisioning (most common)

When a buyer purchases or pulls data from your endpoint via the marketplace UI for the first time, Spartera automatically provisions an endpoint key:

Scoped to the buyer's company (so usage and billing attribute correctly)
Scoped to your endpoint (so the key only works for this one resource)
Read-only

The buyer can then use that key inside the marketplace UI or copy it out to call the endpoint from their own apps, agents, or scripts. This is the model designed for self-service buyers.

→ See Subscribing to Endpoints for the buyer-side flow.

2. Seller-Minted (B2B contracts)

For customers acquired outside the marketplace (direct B2B contracts), you can manually mint an endpoint key from the API Key Management panel on the endpoint edit page:

Dashboard → Endpoints → [Your Endpoint] → API Key Management → Create Key

Or via API:

curl -X POST "https://api.spartera.com/companies/{company_id}/endpoints/{endpoint_id}/keys" \
  -H "x-api-key: your-analytics-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp Production"
  }'

The key is created in your company (not the customer's), and you hand the plain text value to your customer. This is useful for:

Customers who already have a contract and shouldn't go through the marketplace flow
Internal testing keys
Cases where you want to control key issuance manually

Using an Endpoint Key

curl "https://{seller_handle}.api.spartera.com/endpoints/v1/{endpoint_slug}" \
  -H "x-api-key: ep_..."

The subdomain is the seller's company handle. The slug is the endpoint's URL-safe identifier. See Endpoint API Reference for details.

Key Storage and Visibility

Plain text values are only shown once — at the moment of creation. Spartera stores only an HMAC of the key for validation. Once you close the creation dialog, the original value is gone forever.

You can always see	Hidden after creation
Key name, role, type, creation date	The actual key value
Last-used timestamp
Usage count
Active/revoked status

If you lose a key, you can't recover it — you must rotate (revoke + create new).

Rotating a Key

To rotate a key, revoke the old one and create a new one. The old key stops working immediately on revocation. Update your application to use the new key.

# Step 1: Revoke
curl -X DELETE "https://api.spartera.com/companies/{company_id}/api_keys/{api_key_id}" \
  -H "x-api-key: your-admin-key"

# Step 2: Create
curl -X POST "https://api.spartera.com/companies/{company_id}/api_keys" \
  -H "x-api-key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production CI (rotated)", "role_id": 3, "key_type": "analytics"}'

For marketplace-provisioned endpoint keys, returning to the endpoint's product page after revocation will trigger automatic re-provisioning.

Best Practices

Use separate keys per environment. Don't reuse production keys in development. Keys are easy to mint and rotate.

Never commit keys to source control. Use environment variables, secret managers, or per-environment vaults.

Use the lowest-privilege role that works. A reporting service that only reads doesn't need an Admin key. A read-only Analyst (role 1) is enough.

Rotate on incident. If a key is exposed (committed to a public repo, leaked in a log file), revoke immediately and replace.

Set expirations. Keys without expiration dates are forever-valid. For high-trust environments, prefer keys that auto-expire and require periodic re-issuance.

Name keys descriptively. "Acme Production" beats "key_2." When you need to revoke, you'll thank yourself.

Comparing the Two Types in Practice

You're a seller building a data product:
→ Use an analytics key for setup and admin work. Let the marketplace auto-provision endpoint keys for buyers.

You're a buyer consuming data via the marketplace:
→ Click Fetch Data on the endpoint's product page. Spartera issues you an endpoint key automatically. Use it inside the marketplace or copy it to your own apps.

You're a buyer with a direct B2B contract:
→ Your seller will hand you an endpoint key directly. Use it the same way as a marketplace-issued one.

You're integrating an AI agent:
→ Use an endpoint key per endpoint the agent needs access to, or wire up SparteraConnect (MCP) which handles key management for you.

Endpoint API Reference — Where to use endpoint keys
Subscribing to Endpoints — Buyer-side auto-provisioning flow
API Overview — The full API surface
Endpoints Overview — What an endpoint is