API key authentication

An Apso service API key identifies a trusted caller to a deployed backend. It works well for a Next.js backend-for-frontend, a worker, a scheduled job, or another server.

Service keys and user Auth solve different problems

Credential	Identifies	Appropriate location
Apso service API key	A trusted application or process	Server environment or secret manager
User session or token	An individual user	Secure cookie or client credential flow

A shared service key does not tell your backend which end user initiated a request. For a browser product, authenticate the user in your BFF, apply the user’s authorization rules, then call Apso with the server-side service key.

Send a service key


curl https://your-service.example.com/Projects \
  -H "X-API-Key: $APSO_API_KEY"

With the TypeScript SDK:

src/lib/apso.ts


import 'server-only';
import { ApsoClientFactory } from '@apso/sdk';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
});

Create, rotate, and revoke hosted service keys from the service’s API Keys view. See Manage API Keys for the operational workflow.

Give each consumer its own key

Create separate credentials for:

Development, staging, and production
A web BFF and background workers
Independent third-party server integrations
Jobs with different owners or rotation schedules

Descriptive names such as production-nextjs-bff make incident response and rotation easier.

Add product-level machine credentials

Some products issue credentials to their own customers. Model that as application data and validate it in custom code. Store a one-way hash of each secret, show the plaintext once, and associate the record with its owner and status.

Useful fields include:

Key ID or prefix for lookup
Hashed secret
Workspace or organization ID
Display name
Created, last-used, and expiration timestamps
Revocation status

Use a constant-time comparison for hashes and apply rate limiting at the deployment edge or application layer. Never store customer key plaintext after creation.

Rotation sequence

Create a replacement key.
Update the consuming server’s secret.
Deploy or restart the consumer.
Verify one read and one write.
Revoke the old key.