Authentication

All API requests require authentication. ShortKit uses two types of API keys — publishable keys for client-side access and secret keys for server-side operations.

API key types

Key type	Prefix	Header	Purpose	Security
Publishable	`pk_{env}_`	`X-API-Key`	Read-only access to published content and event ingestion	Safe for client-side code. Stored plaintext on server.
Secret	`sk_{env}_`	`Authorization: Bearer`	Full management access — content CRUD, analytics, uploads, configuration	Server-side only. bcrypt-hashed on server, shown once at creation.

Both key types encode the environment (live or test) directly in the prefix, so a single key always maps to exactly one environment.

Secret keys grant full API access. Never expose them in client-side code, mobile apps, public repositories, or browser environments.

Key formats

Publishable keys follow the pattern pk_{env}_{random}:

pk_live_a1b2c3d4e5f6g7h8i9j0...
pk_test_x9y8z7w6v5u4t3s2r1q0...

Secret keys follow the pattern sk_{env}_{id}_{random}:

sk_live_a1b2c3_FgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJk...
sk_test_d4e5f6_AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEf...

Publishable keys

Publishable keys are designed to be embedded in client applications. They provide read-only access to public-facing endpoints. Publishable keys are used by the ShortKit SDK. Pass your publishable key when initializing the SDK:

let shortKit = ShortKit(
    apiKey: "pk_live_a1b2c3d4e5f6g7h8i9j0...",
    config: feedConfig,
    userId: "optional-known-user-id"
)

The SDK attaches the key to every request automatically via the X-API-Key header. You never use a secret key in the SDK, and you don’t need to call any publishable-key endpoints directly — the SDK handles all communication with the ShortKit API.

Secret keys

Secret keys are used for server-to-server communication. They provide full access to all management endpoints. Send the key in the Authorization header as a Bearer token:

curl https://api.shortkit.dev/v1/content \
  -H "Authorization: Bearer sk_live_a1b2c3_FgHiJkLmNoPqRsTuVwXyZ..."

Secret keys are bcrypt-hashed before storage. The plaintext is shown exactly once at creation time and cannot be retrieved afterward. If you lose it, rotate to get a new one.

Endpoints by key type

Publishable key (`X-API-Key` header)

Endpoint	Method	Description
`/v1/content`	GET	List published content (feed)
`/v1/content/{id}`	GET	Get a single content item
`/v1/content/upload`	POST	Upload video files
`/v1/events`	POST	Ingest client-side events
`/v1/surveys/{id}/responses`	POST	Submit a survey response

Secret key (`Authorization: Bearer` header)

Endpoint	Method	Description
`/v1/content/*`	GET / PATCH / DELETE	Content management
`/v1/content/import/*`	POST	Import content from a URL
`/v1/surveys/*`	GET / POST / PUT / DELETE	Survey management
`/v1/events/*`	GET	Query events and analytics
`/v1/analytics/*`	GET	Analytics data
`/v1/ad-config`	GET / PUT	Ad configuration

Environment isolation

Every API key encodes its environment in the prefix — either live or test. These environments are completely isolated:

Environment	Key prefixes	Behavior
Live	`pk_live_`, `sk_live_`	Production content, real video processing, persistent data
Test	`pk_test_`, `sk_test_`	Development and testing, isolated from production

A live key cannot access test data, and a test key cannot access live data. The server extracts the environment from the key prefix and enforces this boundary on every request.

Secret key rotation

If you need to rotate a compromised or aging secret key, use the ShortKit portal. The old key is immediately invalidated when a new one is generated.

Key expiration

API keys do not expire automatically. Both publishable and secret keys remain valid until the secret key is manually rotated. There is no time-based expiration policy — you control the key lifecycle through rotation.

Authentication errors

If authentication fails, the API returns 401 (invalid_api_key) or 403 (forbidden). See Errors for details and response format.

Best practices

Publishable keys are safe for client bundles

Publishable keys grant read-only access to published content and event ingestion. They are designed to be shipped in mobile apps, web embeds, and client-side JavaScript. Treat them like a public identifier, not a secret.

Store secret keys in environment variables only

Never hard-code secret keys in source files or commit them to version control. Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, .env files excluded from git):

# .env (never commit this file)
SHORTKIT_SECRET_KEY=sk_live_a1b2c3_FgHiJkLmNoPqRsTuVwXyZ...

import os
secret_key = os.environ["SHORTKIT_SECRET_KEY"]

Use the correct key type for each context

Mobile apps and browsers: Publishable key (pk_live_ / pk_test_) via X-API-Key header
Backend servers and scripts: Secret key (sk_live_ / sk_test_) via Authorization: Bearer header

Mixing these up either exposes your secret key or blocks legitimate requests with a 403.

Rotate on team changes

When a team member with access to the secret key leaves the organization, rotate the key immediately via POST /v1/org/rotate-secret-key. The old key is invalidated instantly.

Monitor for exposed keys

If a secret key is accidentally committed to a public repository or included in client-side code, rotate it immediately. The old key stops working as soon as rotation completes.

Overview

Reference

API key types

Key formats

Publishable keys

Secret keys

Endpoints by key type

Publishable key (`X-API-Key` header)

Secret key (`Authorization: Bearer` header)

Environment isolation

Secret key rotation

Key expiration

Authentication errors

Best practices

​API key types

​Key formats

​Publishable keys

​Secret keys

​Endpoints by key type

​Publishable key (X-API-Key header)

​Secret key (Authorization: Bearer header)

​Environment isolation

​Secret key rotation

​Key expiration

​Authentication errors

​Best practices

API key types

Key formats

Publishable keys

Secret keys

Endpoints by key type

Publishable key (`X-API-Key` header)

Secret key (`Authorization: Bearer` header)

Environment isolation

Secret key rotation

Key expiration

Authentication errors

Best practices