Authentication

Authentication is only needed for the protected catalog surface. The free decision endpoint and model discovery endpoints do not require an API key. When a bearer key is required, send it in the Authorization header.

There is no Aspas Labs dashboard or self-service key-management screen yet. Use the free decision and model endpoints directly without a key. The current OpenAPI contract requires a bearer key only for catalog creation, reads, and deletion.

Bearer keys

You do not need a bearer key for POST /v1/decisions, GET /v1/models, or GET /v1/models/{model}. For catalog operations, the expected key format is gf_live_...; send it as a bearer token:

cURL

curl https://api.aspaslabs.com/v1/catalogs \
  -X POST \
  -H "Authorization: Bearer $ASPAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "support-actions",
    "model": "goldenfish-g1",
    "choices": ["reset_password", "billing"]
  }'

Use an environment variable or your server’s secret manager. Do not hard-code a key in source code, commit it to Git, or send it from a browser bundle.

Treat an API key like a password. If it is exposed, stop using it and contact Aspas Labs for rotation or revocation instructions. The API contract does not expose a self-service key-management endpoint.

Endpoint access

Endpoint	Key in the current contract	Purpose
`POST /v1/decisions`	Not required (free)	Run a structured decision.
`GET /v1/models`	Not required (free)	List available models.
`GET /v1/models/{model}`	Not required (free)	Read one model descriptor.
`POST /v1/catalogs`	Required	Create a reusable catalog.
`GET /v1/catalogs/{id}`	Required	Read a catalog you own.
`DELETE /v1/catalogs/{id}`	Required	Delete a catalog you own.
`GET /health/live`	Not configured	Check process liveness.
`GET /health/ready`	Not configured	Check inference readiness.

“Not required (free)” means the endpoint has an anonymous security alternative in the OpenAPI document. Your deployment may still apply quotas outside that document.

Authentication failures

When a protected catalog endpoint is missing a key or receives an invalid key, expect a 401 response with the standard error envelope:

401 Unauthorized

{
  "error": {
    "message": "Authentication required.",
    "type": "authentication_error",
    "code": "authentication_required",
    "param": null
  }
}

The exact message and code are server-controlled. Use the HTTP status and error.type for program logic, and keep the message for logs and operator feedback.

Server-side pattern

Store ASPAS_API_KEY in the runtime environment or a secret manager.
Read it only in server-side code.
Add Authorization: Bearer <key> to the outbound request.
Never return the key to a browser or include it in a client-side log.
Remove the header when forwarding user-controlled requests to services that should not receive it.

API keys are only needed for the protected catalog operations in the current contract. Your free decision request can remain keyless.

Get started

Concepts

Guides

API reference

Resources

Bearer keys

Endpoint access

Authentication failures

Server-side pattern

​Bearer keys

​Endpoint access

​Authentication failures

​Server-side pattern

Bearer keys

Endpoint access

Authentication failures

Server-side pattern