API keys

An API key authorizes requests to one generated service. Use service keys for a trusted backend, automation process, or server-side frontend layer. A key must never ship in browser JavaScript or a mobile application bundle.

Create a key

Open the service in Apso Cloud .
Select API Keys.
Click Create API Key.
Give the key a name that identifies its environment and consumer, such as production-nextjs-bff.
Copy the value when it is shown.
Store it in the consumer’s secret manager or server environment.

Copy a new key immediately. The full secret is only shown during creation. The current CLI does not provide apso api-key commands, so create and revoke keys in the service API Keys view.

Call the service

Generated hosted APIs accept the key in the X-API-Key header:


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

Header names are case-insensitive. The service and dashboard may display x-api-key in examples.

Use 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!,
});


const projects = await apso.entity('Projects').get();

Keep this module on the server. In Next.js, import it only from Server Components, Server Actions, route handlers, or other server-only modules.

Choose the credential boundary

Consumer	Recommended access
Next.js BFF	Service key in server environment variables.
Worker or scheduled job	Dedicated service key in the platform secret manager.
Third-party server integration	Dedicated key that can be rotated without affecting other consumers.
Browser application	BFF or user-scoped auth token. Do not expose a service key.
React Native or Flutter	User-scoped token in secure device storage. Do not bundle a service key.

Rotate a key

Create a replacement with a new descriptive name.
Add it to the consuming server environment.
Deploy or restart the consumer.
Verify a read and write request.
Revoke the old key in Apso Cloud.

Use separate keys for development, staging, production, and independent integrations. This keeps rotation local to one environment or consumer.

Deactivate or revoke

Use the service API Keys view to deactivate or revoke a credential. Requests that use the key must fail after revocation. For a planned rotation, update the consumer first, then confirm that the old key no longer works.

Diagnose authentication

Request rejected

Confirm the request targets the service that issued the key.
Check that the key is active.
Remove surrounding quotes, newlines, or whitespace from the stored value.
Verify the request sends X-API-Key.
Create a replacement key when the original value is no longer available.

Browser request works only with the key exposed

Move the request behind a BFF route. The browser calls your BFF, and the BFF calls Apso with the server-side key.

Exercise CRUD routes with curl and the SDK

Test the API

Put an Apso client behind Server Components and route handlers

Connect Next.js

Configure local and hosted secrets

Environment variables