Organizations

An organization is Deeplinq's tenant boundary. It owns credits, model grants, projects, datasets, teams, integrations, policy overrides, and audit lineage. End users exist inside that boundary as opaque subject identifiers supplied by the tenant's trusted backend.

Onboarding checklist

Every organization needs:

1. an internal Deeplinq organization record;
2. at least one authentication path;
3. a positive credit balance;
4. at least one model grant.

Create the organization:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/admin/orgs" \
  -d '{"name":"Acme Corp"}'

The returned UUID remains stable if you later change the organization's name or external issuer binding. Grants and balances key on this UUID.

Authentication paths

Engine API key

Use an engine key for service-to-service integrations and the fastest initial setup:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/api-keys" \
  -d '{"name":"Production backend"}'

The key field is returned once. The engine stores only its hash.

An organization key can carry user attribution:

Authorization: Bearer sk_dl_...
X-End-User-Id: user-42
X-End-User-Roles: org-member

Without X-End-User-Id, calls are organization-level and cannot use owner-scoped resources such as conversations, personal connections, or runs.

Tenant-signed JWT

Use short-lived JWTs when your application is the user identity authority. First bind the JWT issuer:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/bind" \
  -d '{"external_org_ref":"acme-production"}'

Generate an asymmetric keypair in the tenant environment and register only the public key:

openssl genpkey -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 -out acme-private.pem
openssl pkey -in acme-private.pem -pubout -out acme-public.pem

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/keys" -d "{
  \"kid\":\"acme-2026-07\",
  \"alg\":\"RS256\",
  \"public_key\":\"$(awk 'NF {printf \"%s\\\\n\", $0}' acme-public.pem)\"
}"

Supported algorithms are RS256, ES256, and EdDSA. Keep the private key inside the tenant's secret manager.

Credits and model grants

Fund credits with a stable idempotency key:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-credit-2026-07" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/credits" \
  -d '{"amount_micro_usd":100000000}'

Grant each model independently:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/admin/orgs/$ORG_ID/models" \
  -d '{"model":"gpt-5-mini"}'

Revoke a model without changing connector or pricing state:

DELETE /v1/admin/orgs/{org_id}/models/{model}

Roles

Tenant assertions cannot acquire reserved platform-* roles.

Offboarding and rotation

• Revoke old API keys only after replacement traffic succeeds.
• Rotate JWT keys by registering a new kid, switching issuers, then disabling the old key.
• Revoke user-bound API keys when offboarding or demoting a user; Deeplinq does not own a user directory.
• Revoke model grants before removing provider capacity when you need a controlled tenant-facing shutdown.
• Export audit evidence and reconcile billing before deleting external account records.

The admin console's organization detail page combines identity, keys, credits, model grants, integrations, and usage for the same tenant boundary.