Skip to main content

Verify installation and integration

This page provides a single checklist to confirm your deployment and integration work end-to-end.

If you can complete every check here, you have a healthy baseline for production integration work.

What to log for every request​

Log these fields in your backend around every Vluna call:

  • realm_id
  • principal_id
  • Idempotency-Key (for writes)
  • X-Request-Id (if you set it)
  • The full response envelope (store redacted logs if required)

Check 1: service is reachable​

curl​

curl -fsS https://api.us-east-1.vluna.ai/health

TypeScript (SDK)​

// TODO

Python (SDK)​

# TODO

Verify:

  • You receive a success response.

Troubleshoot:

  • If you are self-hosted, confirm vluna/oss is running and ports are reachable.

Check 2: issue a bearer token for a principal​

This proves your service key is valid and the realm scope is correct.

curl​

# This endpoint requires Service Key authentication.
# Use the SDK for the simplest first pass.
curl -sS -X POST 'https://api.us-east-1.vluna.ai/mgt/v1/token/issue' \
  -H 'Content-Type: application/json' \
  -H 'X-Realm-Id: demo-realm-1' \
  -H 'Idempotency-Key: ik_token_issue_0001' \
  -H 'Authorization: SVC-AUTH keyId=pk_example,sig=BASE64,ts=2026-01-10T00:00:00Z,nonce=00000000-0000-0000-0000-000000000000,alg=HMAC-SHA256' \
  -d '{\"principal_id\":\"customer_123\",\"user_id\":\"user_456\",\"scopes\":[\"checkout\",\"portal\"],\"session_ttl_sec\":900}'

TypeScript (SDK)​

// TODO

Python (SDK)​

import asyncio
import os

from vlunaai_sdk import (
  VlunaAIConfig,
  RequestContext,
  ServiceClientOptions,
  ServiceKeyCredentials,
  create_service_client,
)


def env(name: str) -> str:
  v = os.environ.get(name)
  if not v:
    raise RuntimeError(f"Missing env: {name}")
  return v


async def main() -> None:
  client = create_service_client(
    ServiceClientOptions(
      config=VlunaAIConfig(
        base_url=os.environ.get('VLUNA_SERVICE_BASE_URL', 'https://api.us-east-1.vluna.ai/mgt/v1'),
        realm_id=env('VLUNA_REALM_ID'),
      ),
      service_key=ServiceKeyCredentials(
        key_id=env('VLUNA_SERVICE_KEY_ID'),
        secret=env('VLUNA_SERVICE_KEY_SECRET'),
      ),
    )
  )
  try:
    principal_id = 'customer_123'
    token = await client.issue_vluna_token(
      body={
        'principal_id': principal_id,
        'user_id': 'user_456',
        'scopes': ['checkout', 'portal'],
        'session_ttl_sec': 900,
      },
      context=RequestContext(principal_id=principal_id, idempotency_key='ik_token_issue_0001'),
    )
    print(token.model_dump())
  finally:
    await client.close()


asyncio.run(main())

Verify:

  • Response contains access_token and billing_account_id.

Troubleshoot:

  • 401/403: realm is wrong, service key is wrong, or the key is not allowed for the realm.
  • 409: you reused an Idempotency-Key with a different request body.

Check 3: authorize then commit one unit of usage​

This proves the runtime gate loop is functional.

curl​

# These endpoints require Service Key authentication.
# Use the SDK for the simplest first pass.
curl -sS -X POST 'https://api.us-east-1.vluna.ai/mgt/v1/gate/authorize' \
  -H 'Content-Type: application/json' \
  -H 'X-Realm-Id: demo-realm-1' \
  -H 'X-Principal-Id: customer_123' \
  -H 'Idempotency-Key: ik_authorize_0001' \
  -H 'Content-Digest: sha-256=:BASE64SHA256:' \
  -H 'Authorization: SVC-AUTH keyId=pk_example,sig=BASE64,ts=2026-01-10T00:00:00Z,nonce=00000000-0000-0000-0000-000000000000,alg=HMAC-SHA256' \
  -d '{\"feature_code\":\"openai.gpt5\",\"feature_family_code\":\"llm.standard\",\"estimated_quantity_minor\":\"1\"}'

TypeScript (SDK)​

// TODO

Python (SDK)​

import asyncio
import os

from vlunaai_sdk import (
  VlunaAIConfig,
  RequestContext,
  ServiceClientOptions,
  ServiceKeyCredentials,
  create_service_client,
)


def env(name: str) -> str:
  v = os.environ.get(name)
  if not v:
    raise RuntimeError(f"Missing env: {name}")
  return v


async def main() -> None:
  client = create_service_client(
    ServiceClientOptions(
      config=VlunaAIConfig(
        base_url=os.environ.get('VLUNA_SERVICE_BASE_URL', 'https://api.us-east-1.vluna.ai/mgt/v1'),
        realm_id=env('VLUNA_REALM_ID'),
      ),
      service_key=ServiceKeyCredentials(
        key_id=env('VLUNA_SERVICE_KEY_ID'),
        secret=env('VLUNA_SERVICE_KEY_SECRET'),
      ),
    )
  )
  try:
    principal_id = 'customer_123'
    ctx = RequestContext(principal_id=principal_id)

    authz = await client.authorize(
      body={'feature_code': 'openai.gpt5', 'feature_family_code': 'llm.standard', 'estimated_quantity_minor': '1'},
      context=ctx.model_copy(update={'idempotency_key': 'ik_authorize_0001'}),
    )
    if not authz.ok or not authz.data:
      raise RuntimeError(f"authorize failed: {authz.model_dump()}")

    lease_token = authz.data.lease_token
    commit = await client.commit(
      body={'lease_token': lease_token, 'feature_code': 'openai.gpt5', 'quantity_minor': '1', 'labels': {'request_id': 'r-1'}},
      context=ctx.model_copy(update={'idempotency_key': 'ik_commit_0001'}),
    )
    print(commit.model_dump())
  finally:
    await client.close()


asyncio.run(main())

Verify:

  • Authorize response contains lease_token.
  • Commit response contains amount_xusd (it may be 0 depending on pricing configuration) and may include hints.

Troubleshoot:

  • 402: a hard enforcement rule blocked the request (funding, quota, or budget).
  • 429: rate limit. Retry with backoff and keep idempotency keys stable for safe replays.
  • 422: request validation failed (invalid ids, invalid feature/meter, or window/policy issues).

Next steps​