Getting started

Initialize the platform

Configure a provider, price its models, and onboard the first organization.

Initialization happens at runtime. Database migrations run automatically at boot; connectors, models, prices, organizations, and credentials are managed through the admin console or the platform API.

The required sequence

Open /admin for the guided browser workflow. The examples below use the machine API:

export DEEPLINQ_BASE_URL="https://api.example.com"
export DEEPLINQ_ADMIN_USER="admin"
export DEEPLINQ_ADMIN_PASSWORD="..."

admin_curl() {
  curl --fail-with-body --user \
    "$DEEPLINQ_ADMIN_USER:$DEEPLINQ_ADMIN_PASSWORD" \
    -H "Content-Type: application/json" "$@"
}

Keep the break-glass admin credential in a password manager. Tenant tokens cannot acquire the platform-admin role.

1. Register a model connector

This OpenAI example explicitly declares the models the connector may serve and the fallback model used for provider probes and internal calls:

admin_curl -X POST "$DEEPLINQ_BASE_URL/v1/connectors" -d '{
  "key": "openai-production",
  "name": "OpenAI production",
  "kind": "llm",
  "type": "openai",
  "api_key": "sk-...",
  "models": ["gpt-5-mini", "gpt-5.2"],
  "default_model": "gpt-5-mini",
  "default": true
}'

The credential is write-only and sealed with SECRETS_KEY. Registration makes a minimal real provider call. A rejected key is not stored; an unreachable provider may be stored with an explicit verification result so the operator can diagnose network policy.

See connectors for providers, connector kinds, discovery, verification, priorities, and key rotation.

2. Configure model pricing

A model without a pricing row is refused before provider execution. Prices are integer micro-USD per million tokens:

admin_curl -X PUT \
  "$DEEPLINQ_BASE_URL/v1/admin/pricing/gpt-5-mini" -d '{
  "provider": "openai",
  "input_micro_usd_per_mtok": 250000,
  "output_micro_usd_per_mtok": 2000000,
  "margin_pct": 20,
  "tier": "economy"
}'

The numbers above are examples, not current provider prices. Copy the provider's published rates when you configure production.

See models and pricing for units, routing tiers, margin, cache-aware billing, and repricing behavior.

3. Create an organization

ORG_RESPONSE="$(
  admin_curl -X POST "$DEEPLINQ_BASE_URL/v1/admin/orgs" \
    -d '{"name":"Acme Corp"}'
)"
echo "$ORG_RESPONSE"

Record the returned organization UUID as ORG_ID. It is the stable tenant key used by model grants, credits, resources, and audit evidence.

4. Set up the organization's identity

A tenant credential is issued by the platform identity provider, not by the engine. One call does the whole thing — creates the organization there, stamps it as belonging to this engine org, creates its machine user, and mints and seals a client secret:

admin_curl -X POST "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/identity-setup" -d '{
  "admin_email": "admin@acme.com"
}'

That one call also creates the organization's first administrator and grants them org-admin. You supply no password: the engine generates one and returns it as admin_password in that response only, and the identity provider forces them to change it at their first sign-in. It is used once — an organization that already has an administrator ignores admin_email, so re-running never resets a working administrator. Omit the field (send {}) to set the administrator up later.

No credential goes in the request body. The engine holds its own standing provisioning credential — a narrowly-scoped identity-provider service account, never a tenant's or an operator's personal one — configured once when the engine is deployed. Collect the minted secret once, then acknowledge it so the engine drops its own copy:

admin_curl -X POST "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/machine-credentials/secret"
admin_curl -X POST "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/machine-credentials/secret/acknowledge"

That secret is the only copy either side keeps — a lost one means rotating, not re-reading. The organization's identity-provider login domain is derived from the engine org's own name, so give it a real name at creation.

A token naming any other organization is refused with a 401; there is no auto-provisioning. Read back what an organization is bound to with GET /v1/admin/orgs/$ORG_ID/identity-binding, and the setup's own progress with GET /v1/admin/orgs/$ORG_ID/provisioning — useful if a step failed and you are re-running it.

Already provisioned the organization and its machine user at the identity provider yourself? Register the existing objects instead of creating new ones:

admin_curl -X POST \
  "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/identity-binding" -d '{
  "issuer": "https://identity.example.com",
  "remote_org_id": "329487325098234"
}'

See authentication and organizations.

5. Fund credits

Credits use micro-USD, where 1,000,000 equals one USD:

admin_curl -X POST \
  "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/credits" \
  -H "Idempotency-Key: acme-initial-credit" \
  -d '{"amount_micro_usd":100000000}'

This grants USD 100 in engine credit. Always use a stable idempotency key for a retryable funding operation.

6. Grant models

Model access is default-deny:

admin_curl -X POST \
  "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/models" \
  -d '{"model":"gpt-5-mini"}'

Grant auto only when you want intent-based routing:

admin_curl -X POST \
  "$DEEPLINQ_BASE_URL/v1/admin/orgs/$ORG_ID/models" \
  -d '{"model":"auto"}'

The organization must also have concrete entitled models in the tiers the router may select.

7. Verify the tenant path

Using an access token from the organization's machine credential:

export DEEPLINQ_TOKEN="<machine access token>"

curl --fail-with-body "$DEEPLINQ_BASE_URL/v1/models" \
  -H "Authorization: Bearer $DEEPLINQ_TOKEN"

curl --fail-with-body "$DEEPLINQ_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role":"user","content":"Reply with: ready"}]
  }'

If the model is not returned by /v1/models, check all three independent conditions: an enabled connector serves it, a pricing row exists, and the organization has a model grant.

Install Deeplinq

Run the complete local stack and prepare a production deployment.

Authentication

Authenticate with OAuth2 tokens from the platform identity provider — the only tenant authentication method.

On this page

The required sequence1. Register a model connector2. Configure model pricing3. Create an organization4. Set up the organization's identity5. Fund credits6. Grant models7. Verify the tenant pathRecommended next configuration