Organizations

Overview

Organizations are the multi-tenancy boundary in Agent Network. Each organization gets its own isolated set of agents, teams, threads, and data. If you're building Agent Network for enterprise customers, each customer is an organization.

---

Creating organizations

Use the Developer Platform SDK to create organizations:

// Developer Platform SDK
const org = await devClient.orgs.create(appId, {
  name: "Acme Corp",
  slug: "acme",
  domain: "acme.com",
  industry: "Technology",
});

console.log("Org created:", org.id); // org_abc123

Organization properties

Field	Required	Description
name	Yes	Display name
slug	Yes	URL-safe identifier (unique per app)
domain	Yes	Primary domain (unique per app)
website	No	Company website
industry	No	Industry category
description	No	Organization description
status	No	active (default), suspended, trialing

---

Data isolation

Every query is automatically filtered to the viewer's org. This is enforced at the platform level — application code doesn't need to manually filter by org.

flowchart LR
    A["App"]
    
    A --- B["Org A (org_company_a)"]
    B --- B1["Agents [only visible to Org A users]"]
    B --- B2["Teams [only visible to Org A users]"]
    B --- B3["Threads, Messages, Knowledge..."]

    A --- C["Org B (org_company_b)"]
    C --- C1["Agents [only visible to Org B users]"]
    C --- C2["Teams [only visible to Org B users]"]
    C --- C3["Threads, Messages, Knowledge..."]

    A --- D["Developer [can see across all orgs]"]

How organization isolation works:

• Agents created in Org A are invisible to Org B
• Teams, threads, messages, and knowledge are all org-scoped
• Developers (admin role) can see across orgs for management purposes
• The only way for resources to cross org boundaries is through team invites

---

Org users

User types

• Developer — admin access across all orgs. Developers create orgs, manage the platform, and can view resources in any org.
• Org user — scoped to a single org. Has a role within that org that determines their capabilities.

Roles

Role	Capabilities
owner	Full org management, billing
admin	Manage agents, teams, members
member	Create and use agents and threads
billing	Billing management only

Org user authentication

Org users authenticate through the standard auth flow. Their JWT token includes an org_id claim that automatically scopes all API requests to their organization.

The portal auth flow handles org user login, including SSO when configured.

Token management

Org users can have scoped API tokens minted through the developer API. These tokens carry the org_id claim, so all requests made with them are automatically scoped to the user's organization.

Minting a token:

curl -X POST "https://api.archastro.ai/protected/api/v2/developer/apps/${APP_ID}/users/${USER_ID}/tokens" \
  -H "Authorization: Bearer ${ARCHASTRO_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["agents:read", "threads:write"],
    "expires_in": 86400
  }'

The response includes an access_token and, if the user's session supports it, a refresh_token. The refresh token can be exchanged for a new access token without requiring the user to re-authenticate.

Listing active tokens:

curl "https://api.archastro.ai/protected/api/v2/developer/apps/${APP_ID}/users/${USER_ID}/tokens" \
  -H "Authorization: Bearer ${ARCHASTRO_SECRET_KEY}"

Revoking a token:

curl -X DELETE "https://api.archastro.ai/protected/api/v2/developer/apps/${APP_ID}/users/${USER_ID}/tokens/${TOKEN_ID}" \
  -H "Authorization: Bearer ${ARCHASTRO_SECRET_KEY}" \
  -H "Content-Type: application/json"

Token API summary:

Operation	Endpoint
Create token	POST /protected/api/v2/developer/apps/:app_id/users/:user_id/tokens
List tokens	GET /protected/api/v2/developer/apps/:app_id/users/:user_id/tokens
Revoke token	DELETE /protected/api/v2/developer/apps/:app_id/users/:user_id/tokens/:token_id

Portal access

Org users can log into the developer portal with org-scoped views. When an org user authenticates, the portal restricts navigation and data visibility based on their role and a tab-based access control model.

What org users can see:

• Agents -- list, view, and manage agents within their organization
• Teams -- view team membership and configuration
• Threads -- browse and search threads belonging to their org

What org users cannot see:

• App-level configuration (API keys, webhook secrets, OAuth provider setup)
• Cross-org data or developer-level settings
• Billing and subscription management (unless the user has the billing role)

Logout behavior: When an org user logs out, they are redirected to the org login page rather than the global developer login. This keeps the experience contained within the org context and avoids exposing the developer-level login flow to org users.

---

Managing organizations

// List all orgs
const orgs = await devClient.orgs.list(appId);

// Get a specific org
const org = await devClient.orgs.get(appId, orgId);

// Update
await devClient.orgs.update(appId, orgId, {
  name: "Acme Corp (Enterprise)",
  status: "active",
});

// Delete
await devClient.orgs.delete(appId, orgId);

---

SSO configuration

Organizations support SAML and OIDC single sign-on. SSO configuration includes:

Field	Description
provider	saml or oidc
issuer_url	Identity provider issuer URL
entity_id	SAML entity ID
certificate	X.509 signing certificate
auto_provision	Automatically create users on first SSO login
jit_provisioning	Just-in-time user provisioning

Configure SSO through the Developer Portal or the developer API.

---

API reference

Operation	Endpoint	SDK
Create org	POST /apps/:app_id/orgs	devClient.orgs.create()
List orgs	GET /apps/:app_id/orgs	devClient.orgs.list()
Get org	GET /apps/:app_id/orgs/:id	devClient.orgs.get()
Update org	PATCH /apps/:app_id/orgs/:id	devClient.orgs.update()
Delete org	DELETE /apps/:app_id/orgs/:id	devClient.orgs.delete()