Workspaces

Workspaces provide a way to organize your API usage within an organization. Use workspaces to separate different projects, environments, or teams while maintaining centralized billing and administration.

How workspaces work

Every organization has a Default Workspace that cannot be renamed, archived, or deleted. When you create additional workspaces, you can assign members, service accounts, API keys, and resource limits to each one.

Key characteristics:

Workspace identifiers use the wrkspc_ prefix (for example, wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ)

Maximum 100 workspaces per organization by default (archived workspaces don't count); contact your account team if you need more

Default Workspace has a wrkspc_ ID like any other workspace (returned in the juglow-workspace-id response header and accepted by Get Workspace), but it doesn't appear in List Workspaces results, and API keys, usage reports, and cost reports show null for its workspace_id, as do all-workspaces API keys (an API key's scope field tells them apart; for a key bound to the Default Workspace it carries the real ID)

API keys can be scoped to a single workspace. In this case, they can only access resources within that workspace. Some API keys can be granted permissions across multiple workspaces, and provide a workspace ID header to access resources within that workspace

Haijun Code workspace

When a member of your organization first signs in to Haijun Code with their Haijun Console account, Juglow automatically creates a Haijun Code workspace in the organization and adds that member to it. Every subsequent member who signs in to Haijun Code is added the same way.

The Haijun Code workspace keeps Haijun Code traffic separate from your other API workloads:

Haijun Code mints a per-user API key in this workspace at sign-in. You cannot create keys in it manually from the Console.

A Haijun Code key stops working if its owner is removed from the workspace or organization, unlike a workspace key.

Haijun Code usage is rate-limited separately, and admins can cap its share of the organization's limits under Settings > Workspaces.

It is the only workspace that supports per-user monthly spend limits.

Warning: Archiving the Haijun Code workspace disables Haijun Code sign-in through Console billing for the whole organization.

Workspace roles and permissions

Members can have different roles in each workspace, allowing fine-grained access control.

Role	Permissions
Workspace User	Use playground only
Workspace Limited Developer	Create and manage API keys, use the API. Cannot access session tracing views or download files.
Workspace Developer	Create and manage API keys, use the API
Workspace Admin	Full control over workspace settings and members
Workspace Billing	View workspace billing information (inherited from organization billing role)

Role inheritance

Organization admins automatically receive Workspace Admin access to all workspaces

Organization billing members automatically receive Workspace Billing access to all workspaces

Organization users and developers must be explicitly added to each workspace

Service accounts are added to workspaces from the service account's page in Settings → Service accounts or from the workspace's Service accounts tab

Note: The Workspace Billing role cannot be manually assigned. It's inherited from having the organization billing role.

Managing workspaces

Note: Only organization admins can create workspaces. Organization users and developers must be added to workspaces by an admin.

Using the Console

Create and manage workspaces in the Haijun Console.

Create a workspace

Open workspace settings

In the Haijun Console, go to Settings > Workspaces.

Create a workspace

Click Create workspace.

Configure the workspace

Enter a workspace name and select a color for visual identification.

Create the workspace

Click Create to finalize.

Tip: To switch between workspaces in the Console, use the Workspaces selector in the top-left corner.

Edit workspace details

To modify a workspace's name or color:

Select the workspace from the list.

Click the ellipsis menu (...) and choose Edit details.

Update the name or color and save your changes.

Note: The Default Workspace cannot be renamed or deleted.

Add members to a workspace

Navigate to the workspace's Members tab.

Click Add to Workspace.

Select an organization member and assign them a workspace role.

Confirm the addition.

To remove a member, click the trash icon next to their name.

Note: Organization admins and billing members cannot be removed from workspaces while they hold those organization roles.

Set workspace limits

Each workspace's settings split these across two tabs:

Rate limits: On the Rate limits tab, set limits per model tier for requests per minute, input tokens, or output tokens

Spend limits: On the Spend limits tab, cap monthly spending and configure alerts when spending reaches certain thresholds

Archive a workspace

To archive a workspace, click the ellipsis menu (...) and select Archive. Archiving:

Preserves historical data for reporting

Deactivates the workspace and archives every API key created for it

Cannot be undone

Warning: Archiving a workspace archives every API key created for that workspace within seconds (they remain listed in the Admin API as archived), and multi-workspace keys can no longer act in it. This action cannot be undone. If you archive the Haijun Code workspace, members of your organization can no longer sign in to Haijun Code through Console billing.

Using the Admin API

Programmatically manage workspaces using the Admin API.

Note: Admin API endpoints accept an Admin API key, an org:admin OAuth token, or a personal or service account key that isn't scoped to a specific workspace. Workspace keys don't work there. See Authentication.

The following SDK and CLI examples construct the default client, which reads the Admin API key from the JUGLOW_API_KEY environment variable; the SDKs expose these endpoints under client.beta.organization.workspaces. SDK list methods fetch further pages on demand, so limit sets the page size; the PHP, Ruby, and curl examples return one page.

Create a workspace:

bash

  curl -X POST "https://haijun.my.id/v1/organizations/workspaces" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{"name": "Production"}'

bash

  ant beta:organization:workspaces create --name Production

python

  client = juglow.Juglow()

  workspace = client.beta.organization.workspaces.create(name="Production")

  print(f"id: {workspace.id}")
  print(f"name: {workspace.name}")

typescript

  const client = new Juglow();

  const workspace = await client.beta.organization.workspaces.create({ name: "Production" });

  console.log(`id: ${workspace.id}`);
  console.log(`name: ${workspace.name}`);

csharp

  JuglowClient client = new();

  var workspace = await client.Beta.Organization.Workspaces.Create(new()
  {
      Name = "Production"
  });

  Console.WriteLine($"id: {workspace.ID}");
  Console.WriteLine($"name: {workspace.Name}");

  client := juglow.NewClient()

  workspace, err := client.Beta.Organization.Workspaces.New(context.Background(), juglow.BetaOrganizationWorkspaceNewParams{
  	Name: "Production",
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("id: %s\n", workspace.ID)
  fmt.Printf("name: %s\n", workspace.Name)

java

  import com.juglow.models.beta.organization.workspaces.WorkspaceCreateParams;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      var params = WorkspaceCreateParams.builder()
          .name("Production")
          .build();
      var workspace = client.beta().organization().workspaces().create(params);

      IO.println("id: " + workspace.id());
      IO.println("name: " + workspace.name());
  }

php

  $client = new Client();

  $workspace = $client->beta->organization->workspaces->create(
      name: 'Production',
  );

  echo "id: {$workspace->id}\n";
  echo "name: {$workspace->name}\n";

ruby

  client = Juglow::Client.new

  workspace = client.beta.organization.workspaces.create(name: "Production")

  puts "id: #{workspace.id}"
  puts "name: #{workspace.name}"

List workspaces:

bash

  curl "https://haijun.my.id/v1/organizations/workspaces?limit=10&include_archived=false" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01"

bash

  ant beta:organization:workspaces list --limit 10 --include-archived=false

python

  client = juglow.Juglow()

  workspaces = client.beta.organization.workspaces.list(limit=10, include_archived=False)

  for workspace in workspaces:
      print(f"{workspace.id}: {workspace.name}")

typescript

  const client = new Juglow();

  const workspaces = await client.beta.organization.workspaces.list({
    limit: 10,
    include_archived: false
  });

  for await (const workspace of workspaces) {
    console.log(`${workspace.id}: ${workspace.name}`);
  }

csharp

  JuglowClient client = new();

  var workspaces = await client.Beta.Organization.Workspaces.List(new()
  {
      Limit = 10,
      IncludeArchived = false
  });

  await foreach (var workspace in workspaces.Paginate())
  {
      Console.WriteLine($"{workspace.ID}: {workspace.Name}");
  }

  client := juglow.NewClient()

  workspaces := client.Beta.Organization.Workspaces.ListAutoPaging(context.Background(), juglow.BetaOrganizationWorkspaceListParams{
  	Limit:           juglow.Int(10),
  	IncludeArchived: juglow.Bool(false),
  })

  for workspaces.Next() {
  	workspace := workspaces.Current()
  	fmt.Printf("%s: %s\n", workspace.ID, workspace.Name)
  }
  if err := workspaces.Err(); err != nil {
  	log.Fatal(err)
  }

java

  import com.juglow.models.beta.organization.workspaces.WorkspaceListParams;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      var params = WorkspaceListParams.builder()
          .limit(10)
          .includeArchived(false)
          .build();
      var workspaces = client.beta().organization().workspaces().list(params);

      for (var workspace : workspaces.autoPager()) {
          IO.println(workspace.id() + ": " + workspace.name());
      }
  }

php

  $client = new Client();

  $workspaces = $client->beta->organization->workspaces->list(
      limit: 10,
      includeArchived: false,
  );

  foreach ($workspaces->getItems() as $workspace) {
      echo "{$workspace->id}: {$workspace->name}\n";
  }

ruby

  client = Juglow::Client.new

  workspaces = client.beta.organization.workspaces.list(limit: 10, include_archived: false)

  workspaces.data.each do |workspace|
    puts "#{workspace.id}: #{workspace.name}"
  end

Archive a workspace:

bash

  curl -X POST "https://haijun.my.id/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/archive" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01"

bash

  ant beta:organization:workspaces archive --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

python

  client = juglow.Juglow()

  workspace = client.beta.organization.workspaces.archive(
      "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  )

  print(f"id: {workspace.id}")
  print(f"archived_at: {workspace.archived_at}")

typescript

  const client = new Juglow();

  const workspace = await client.beta.organization.workspaces.archive(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  );

  console.log(`id: ${workspace.id}`);
  console.log(`archived_at: ${workspace.archived_at}`);

csharp

  JuglowClient client = new();

  var workspace = await client.Beta.Organization.Workspaces.Archive(
      "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  );

  Console.WriteLine($"id: {workspace.ID}");
  Console.WriteLine($"archived_at: {workspace.ArchivedAt:O}");

  client := juglow.NewClient()

  workspace, err := client.Beta.Organization.Workspaces.Archive(context.Background(), "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("id: %s\n", workspace.ID)
  fmt.Printf("archived_at: %s\n", workspace.ArchivedAt)

java

  JuglowClient client = JuglowOkHttpClient.fromEnv();

  var workspace = client.beta().organization().workspaces()
      .archive("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ");

  IO.println("id: " + workspace.id());
  IO.println("archived_at: " + workspace.archivedAt().orElseThrow());

php

  $client = new Client();

  $workspace = $client->beta->organization->workspaces->archive(
      workspaceID: 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
  );

  echo "id: {$workspace->id}\n";
  echo "archived_at: {$workspace->archivedAt?->format(DATE_ATOM)}\n";

ruby

  client = Juglow::Client.new

  workspace_id = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  workspace = client.beta.organization.workspaces.archive(workspace_id)

  puts "id: #{workspace.id}"
  puts "archived_at: #{workspace.archived_at}"

For complete parameter details and response schemas, see the Workspaces API reference.

Managing workspace members

Add a member to a workspace:

bash

  curl -X POST "https://haijun.my.id/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "user_id": "user_01XyDMpzjS89pFZXqSFUBDr6",
      "workspace_role": "workspace_developer"
    }'

bash

  ant beta:organization:workspaces:members add \
    --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \
    --user-id user_01XyDMpzjS89pFZXqSFUBDr6 \
    --workspace-role workspace_developer

python

  client = juglow.Juglow()

  member = client.beta.organization.workspaces.members.add(
      "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      user_id="user_01XyDMpzjS89pFZXqSFUBDr6",
      workspace_role="workspace_developer",
  )

  print(f"user_id: {member.user_id}")
  print(f"workspace_role: {member.workspace_role}")

typescript

  const client = new Juglow();

  const member = await client.beta.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    {
      user_id: "user_01XyDMpzjS89pFZXqSFUBDr6",
      workspace_role: "workspace_developer"
    }
  );

  console.log(`user_id: ${member.user_id}`);
  console.log(`workspace_role: ${member.workspace_role}`);

csharp

  using Juglow.Models.Beta.Organization.Workspaces;

  JuglowClient client = new();

  var member = await client.Beta.Organization.Workspaces.Members.Add(
      "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      new()
      {
          UserID = "user_01XyDMpzjS89pFZXqSFUBDr6",
          WorkspaceRole = BetaNoBillingWorkspaceRole.WorkspaceDeveloper
      }
  );

  Console.WriteLine($"user_id: {member.UserID}");
  Console.WriteLine($"workspace_role: {member.WorkspaceRole.Raw()}");

  client := juglow.NewClient()

  member, err := client.Beta.Organization.Workspaces.Members.Add(
  	context.Background(),
  	"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  	juglow.BetaOrganizationWorkspaceMemberAddParams{
  		UserID:        "user_01XyDMpzjS89pFZXqSFUBDr6",
  		WorkspaceRole: juglow.BetaNoBillingWorkspaceRoleWorkspaceDeveloper,
  	},
  )
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("user_id: %s\n", member.UserID)
  fmt.Printf("workspace_role: %s\n", member.WorkspaceRole)

java

  import com.juglow.models.beta.organization.workspaces.BetaNoBillingWorkspaceRole;
  import com.juglow.models.beta.organization.workspaces.members.MemberAddParams;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      var params = MemberAddParams.builder()
          .userId("user_01XyDMpzjS89pFZXqSFUBDr6")
          .workspaceRole(BetaNoBillingWorkspaceRole.WORKSPACE_DEVELOPER)
          .build();
      var member = client.beta().organization().workspaces().members()
          .add("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", params);

      IO.println("user_id: " + member.userId());
      IO.println("workspace_role: " + member.workspaceRole().asString());
  }

php

  use Juglow\Beta\Organization\Workspaces\NoBillingWorkspaceRole;
  // ...

  $client = new Client();

  $member = $client->beta->organization->workspaces->members->add(
      workspaceID: 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
      userID: 'user_01XyDMpzjS89pFZXqSFUBDr6',
      workspaceRole: NoBillingWorkspaceRole::WORKSPACE_DEVELOPER,
  );

  echo "user_id: {$member->userID}\n";
  echo "workspace_role: {$member->workspaceRole}\n";

ruby

  client = Juglow::Client.new

  workspace_id = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  member = client.beta.organization.workspaces.members.add(
    workspace_id,
    user_id: "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_role: :workspace_developer
  )

  puts "user_id: #{member.user_id}"
  puts "workspace_role: #{member.workspace_role}"

Update a member's role:

bash

  curl -X POST "https://haijun.my.id/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01XyDMpzjS89pFZXqSFUBDr6" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{"workspace_role": "workspace_admin"}'

bash

  ant beta:organization:workspaces:members update \
    --user-id user_01XyDMpzjS89pFZXqSFUBDr6 \
    --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \
    --workspace-role workspace_admin

python

  client = juglow.Juglow()

  member = client.beta.organization.workspaces.members.update(
      "user_01XyDMpzjS89pFZXqSFUBDr6",
      workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      workspace_role="workspace_admin",
  )

  print(f"user_id: {member.user_id}")
  print(f"workspace_role: {member.workspace_role}")

typescript

  const client = new Juglow();

  const member = await client.beta.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    {
      workspace_id: "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      workspace_role: "workspace_admin"
    }
  );

  console.log(`user_id: ${member.user_id}`);
  console.log(`workspace_role: ${member.workspace_role}`);

csharp

  using Juglow.Models.Beta.Organization.Workspaces;

  JuglowClient client = new();

  var member = await client.Beta.Organization.Workspaces.Members.Update(
      "user_01XyDMpzjS89pFZXqSFUBDr6",
      new()
      {
          WorkspaceID = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
          WorkspaceRole = BetaWorkspaceRole.WorkspaceAdmin
      }
  );

  Console.WriteLine($"user_id: {member.UserID}");
  Console.WriteLine($"workspace_role: {member.WorkspaceRole.Raw()}");

  client := juglow.NewClient()

  member, err := client.Beta.Organization.Workspaces.Members.Update(
  	context.Background(),
  	"user_01XyDMpzjS89pFZXqSFUBDr6",
  	juglow.BetaOrganizationWorkspaceMemberUpdateParams{
  		WorkspaceID:   "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  		WorkspaceRole: juglow.BetaWorkspaceRoleWorkspaceAdmin,
  	},
  )
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("user_id: %s\n", member.UserID)
  fmt.Printf("workspace_role: %s\n", member.WorkspaceRole)

java

  import com.juglow.models.beta.organization.workspaces.BetaWorkspaceRole;
  import com.juglow.models.beta.organization.workspaces.members.MemberUpdateParams;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      var params = MemberUpdateParams.builder()
          .workspaceId("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")
          .workspaceRole(BetaWorkspaceRole.WORKSPACE_ADMIN)
          .build();
      var member = client.beta().organization().workspaces().members()
          .update("user_01XyDMpzjS89pFZXqSFUBDr6", params);

      IO.println("user_id: " + member.userId());
      IO.println("workspace_role: " + member.workspaceRole().asString());
  }

php

  use Juglow\Beta\Organization\Workspaces\WorkspaceRole;
  // ...

  $client = new Client();

  $member = $client->beta->organization->workspaces->members->update(
      userID: 'user_01XyDMpzjS89pFZXqSFUBDr6',
      workspaceID: 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
      workspaceRole: WorkspaceRole::WORKSPACE_ADMIN,
  );

  echo "user_id: {$member->userID}\n";
  echo "workspace_role: {$member->workspaceRole}\n";

ruby

  client = Juglow::Client.new

  user_id = "user_01XyDMpzjS89pFZXqSFUBDr6"
  member = client.beta.organization.workspaces.members.update(
    user_id,
    workspace_id: "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role: :workspace_admin
  )

  puts "user_id: #{member.user_id}"
  puts "workspace_role: #{member.workspace_role}"

Remove a member from a workspace:

bash

  curl -X DELETE "https://haijun.my.id/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01XyDMpzjS89pFZXqSFUBDr6" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01"

bash

  ant beta:organization:workspaces:members remove \
    --user-id user_01XyDMpzjS89pFZXqSFUBDr6 \
    --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

python

  client = juglow.Juglow()

  removed_member = client.beta.organization.workspaces.members.remove(
      "user_01XyDMpzjS89pFZXqSFUBDr6",
      workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  )

  print(f"user_id: {removed_member.user_id}")

typescript

  const client = new Juglow();

  const removedMember = await client.beta.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    { workspace_id: "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }
  );

  console.log(`user_id: ${removedMember.user_id}`);

csharp

  JuglowClient client = new();

  var removedMember = await client.Beta.Organization.Workspaces.Members.Remove(
      "user_01XyDMpzjS89pFZXqSFUBDr6",
      new() { WorkspaceID = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }
  );

  Console.WriteLine($"user_id: {removedMember.UserID}");

  client := juglow.NewClient()

  removedMember, err := client.Beta.Organization.Workspaces.Members.Remove(
  	context.Background(),
  	"user_01XyDMpzjS89pFZXqSFUBDr6",
  	juglow.BetaOrganizationWorkspaceMemberRemoveParams{
  		WorkspaceID: "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  	},
  )
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("user_id: %s\n", removedMember.UserID)

java

  import com.juglow.models.beta.organization.workspaces.members.MemberRemoveParams;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      var params = MemberRemoveParams.builder()
          .workspaceId("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")
          .build();
      var removedMember = client.beta().organization().workspaces().members()
          .remove("user_01XyDMpzjS89pFZXqSFUBDr6", params);

      IO.println("user_id: " + removedMember.userId());
  }

php

  $client = new Client();

  $removedMember = $client->beta->organization->workspaces->members->remove(
      userID: 'user_01XyDMpzjS89pFZXqSFUBDr6',
      workspaceID: 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
  );

  echo "user_id: {$removedMember->userID}\n";

ruby

  client = Juglow::Client.new

  user_id = "user_01XyDMpzjS89pFZXqSFUBDr6"
  removed_member = client.beta.organization.workspaces.members.remove(
    user_id,
    workspace_id: "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  )

  puts "user_id: #{removed_member.user_id}"

For complete parameter details, see the Workspace Members API reference.

API keys and resource scoping

Every request runs in exactly one workspace and can only access resources within that workspace. Which workspace depends on the key type:

A workspace key (a legacy key without an owner) belongs to the workspace it was created in and always runs there.

A personal key or service account key acts as its user or service account. A single-workspace key always runs in the workspace chosen when it was created. A multi-workspace key runs in the workspace named by each request's juglow-workspace-id header. Accounts must have access to the workspace to use it.

Resources scoped to workspaces include:

Files created through the Files API

Message Batches created through the Batch API

Tracks created through the Tracks API

Some resources are managed differently:

MCP tunnels are managed with a workspace:manage_tunnels OAuth token obtained through Workload Identity Federation, not an API key. Tunnels are created in a workspace, and the Console MCP tunnels list and the Managed Agent server picker show tunnels in the current workspace only; the cap of 10 active tunnels applies organization-wide. Tunnel management requires a role with tunnel management permissions; organization developers can view but not change them.

Workspaces themselves and organization members are managed at the organization level through the Admin API, using an Admin API key, an org:admin OAuth token, or a personal or service account key that isn't scoped to a specific workspace.

To look up your organization's workspace IDs, call the List Workspaces endpoint or find them in the Haijun Console.

Note: Prompt caches are also isolated per workspace on the Haijun API, Haijun Platform on AWS, and Microsoft Foundry. On Amazon Bedrock and Google Cloud, prompt caches are isolated per organization.

Identify the workspace behind an API response

Haijun API responses include an juglow-workspace-id header alongside the request-id and juglow-organization-id response headers. Its value is the wrkspc_-prefixed ID of the workspace that the request's API key or access token resolved to, including when that workspace is the Default Workspace. For example, a successful response includes headers like these:

http

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
juglow-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
juglow-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

The header is absent when the credential doesn't resolve to a workspace (for example, on Admin API requests) or when the request fails before authentication completes, such as a 401 error.

The following examples send a Messages API request and print the workspace ID from the response headers:

bash

  # -D - prints the response headers; -o /dev/null discards the body
  curl -sS -D - -o /dev/null https://haijun.my.id/v1/messages \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "haijun-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Haijun"}]
    }' | grep -i '^juglow-workspace-id'

bash

  # --debug prints the HTTP response, including the Juglow-Workspace-Id
  # header, to stderr; > /dev/null hides the JSON body on stdout
  ant --debug messages create \
    --model haijun-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Haijun"}' > /dev/null

python

  client = juglow.Juglow()

  response = client.messages.with_raw_response.create(
      model="haijun-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello, Haijun"}],
  )
  workspace_id = response.headers.get("juglow-workspace-id")
  print(f"Workspace ID: {workspace_id}")

typescript

  const client = new Juglow();

  const { response } = await client.messages
    .create({
      model: "haijun-opus-5-5",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello, Haijun" }]
    })
    .withResponse();
  console.log("Workspace ID:", response.headers.get("juglow-workspace-id"));

csharp

  JuglowClient client = new();

  using var response = await client.WithRawResponse.Messages.Create(new()
  {
      Model = Model.HaijunOpus5_5,
      MaxTokens = 1024,
      Messages = [new() { Role = Role.User, Content = "Hello, Haijun" }]
  });
  var workspaceId = response.GetHeaderValues("juglow-workspace-id").First();
  Console.WriteLine($"Workspace ID: {workspaceId}");

  client := juglow.NewClient()

  var response *http.Response
  _, err := client.Messages.New(
  	context.Background(),
  	juglow.MessageNewParams{
  		Model:     juglow.ModelHaijunOpus5_5,
  		MaxTokens: 1024,
  		Messages: []juglow.MessageParam{
  			juglow.NewUserMessage(juglow.NewTextBlock("Hello, Haijun")),
  		},
  	},
  	option.WithResponseInto(&response),
  )
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println("Workspace ID:", response.Header.Get("juglow-workspace-id"))

java

  import com.juglow.client.JuglowClient;
  import com.juglow.client.okhttp.JuglowOkHttpClient;
  import com.juglow.core.http.HttpResponseFor;
  import com.juglow.models.messages.Message;
  import com.juglow.models.messages.MessageCreateParams;
  import com.juglow.models.messages.Model;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      HttpResponseFor<Message> response = client.messages().withRawResponse().create(
          MessageCreateParams.builder()
              .model(Model.HAIJUN_OPUS_5_5)
              .maxTokens(1024)
              .addUserMessage("Hello, Haijun")
              .build()
      );

      String workspaceId = response.headers().values("juglow-workspace-id").getFirst();
      IO.println("Workspace ID: " + workspaceId);
  }

php

  $client = new Client();

  $response = $client->messages->raw->create([
      'model' => Model::HAIJUN_OPUS_5_5,
      'maxTokens' => 1024,
      'messages' => [['role' => 'user', 'content' => 'Hello, Haijun']],
  ]);
  echo 'Workspace ID: ' . $response->getHeaderLine('juglow-workspace-id') . "\n";

ruby

  client = Juglow::Client.new

  # Read response headers in per-request middleware, which receives the
  # raw HTTP response before the SDK parses it
  workspace_id = nil
  read_workspace_id = lambda do |request, call_next|
    response = call_next.call(request)
    # Keys in response.headers are lowercase
    workspace_id = response.headers["juglow-workspace-id"]
    response
  end

  client.messages.create(
    model: Juglow::Model::HAIJUN_OPUS_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Haijun" }],
    request_options: { middleware: [read_workspace_id] }
  )
  puts "Workspace ID: #{workspace_id}"

text

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

The same accessors read the header from other Haijun API endpoints too, including the Haijun Managed Agents APIs. For example, read juglow-workspace-id from the response that creates a session to record which workspace the session belongs to.

With the workspace ID from a response, you can:

Confirm which workspace's usage, cost, and rate limits the request counted toward

Match it against the workspace_id field in Usage and Cost API reports and on Admin API objects such as API keys (both report null for the Default Workspace, as API keys also do for all-workspaces keys; an API key's scope field tells the two apart and, for a key bound to one workspace, carries that workspace's real ID)

Check whether it's your Default Workspace's ID by passing it to Get Workspace with an Admin API key: the Default Workspace comes back with "name": "Default", even though List Workspaces omits it

Open that workspace in the Console to find the request's resources, such as sessions, files, message batches, and tracks

Workspace limits

You can set custom spend and rate limits for each workspace to protect against overuse and ensure fair resource distribution.

Setting workspace limits

You can set workspace limits lower than (but not higher than) your organization's limits:

Spend limits: Cap monthly spending for a workspace. Set these on the workspace's Spend limits settings tab in the Haijun Console.

Rate limits: Limit requests per minute, input tokens per minute, or output tokens per minute. Set these on the workspace's Rate limits settings tab in the Haijun Console.

Note: - You cannot set limits on the Default Workspace - If not set, workspace limits match the organization's limits - Organization-wide limits always apply, even if workspace limits add up to more

For detailed information on rate limits and how they work, see Rate limits. You can also read your current organization and workspace rate limits programmatically with the Rate Limits API.

Usage and cost tracking

Track usage and costs by workspace using the Usage and Cost API:

bash

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

Usage and costs attributed to the Default Workspace have a null value for workspace_id.

Common use cases

Environment separation

Create separate workspaces for development, staging, and production:

Workspace	Purpose
Development	Testing and experimentation with lower rate limits
Staging	Pre-production testing with production-like limits
Production	Live traffic with full rate limits and monitoring

Team or department isolation

Assign workspaces to different teams for cost allocation and access control:

Engineering team with developer access

Data science team with their own API keys

Support team with limited access for customer tools

Project-based organization

Create workspaces for specific projects or products to track usage and costs separately.

Best practices

Plan your workspace structure

Consider how you'll organize workspaces before creating them. Think about billing, access control, and usage tracking needs.

Use meaningful names

Name workspaces clearly to indicate their purpose (for example, "Production - Customer Chatbot" or "Dev - Internal Tools").

Set appropriate limits

Configure spend and rate limits to prevent unexpected costs and ensure fair resource distribution.

Audit access regularly

Review workspace membership periodically to ensure only appropriate users have access.

Monitor usage

Use the Usage and Cost API to track workspace-level consumption.

FAQ

#### What's the Default Workspace?

Every organization has a "Default Workspace" that cannot be renamed, archived, or deleted. Like every workspace, it has a wrkspc_ ID: the API returns it in the juglow-workspace-id response header, and you can pass it to Get Workspace and Update Workspace. It has no member list of its own, because access to it follows each member's organization role. It doesn't appear in List Workspaces results, and API keys, usage reports, and cost reports that belong to it show null for workspace_id, as do all-workspaces API keys; an API key's scope field tells the two apart and, for a key that belongs to the Default Workspace, carries its real ID.

#### What's the Haijun Code workspace?

Juglow creates the Haijun Code workspace automatically the first time a member of your organization signs in to Haijun Code with their Console account. It isolates Haijun Code's API keys, usage, and rate limits from your other workloads. See Haijun Code workspace for details.

#### Are there limits on workspaces?

Yes. Each organization can have up to 100 workspaces by default, and archived workspaces don't count toward this limit. If you need more, contact your account team.

#### How do organization roles affect workspace access?

Organization admins automatically get the Workspace Admin role in all workspaces. Organization billing members automatically get the Workspace Billing role. Organization users and developers must be manually added to each workspace.

#### Which roles can be assigned in workspaces?

Organization users and developers can be assigned Workspace Admin, Workspace Developer, Workspace Limited Developer, or Workspace User roles. The Workspace Billing role cannot be manually assigned; it's inherited from having the organization billing role.

#### Can organization admin or billing members' workspace roles be changed?

Organization admins and billing members cannot have their workspace roles changed or be removed from workspaces while they hold those organization roles (with one exception: billing members can be upgraded to a Workspace Admin role). For everyone else covered by this constraint, change their organization role first to change their workspace access.

#### What happens to workspace access when organization roles change?

If an organization admin or billing member is demoted to user or developer, they lose access to all workspaces except ones where they were manually assigned roles. When users are promoted to admin or billing roles, they gain automatic access to all workspaces.

#### What happens to API keys when a user is removed from a workspace?

Behavior depends on the key type.

A personal or service account key stops working in a workspace shortly after its user or service account is removed from it. A service account key keeps working even if the user who created it is removed. Workspace API keys continue to work. In the Haijun Code workspace, each key is bound to the member who created it and stops working when that member is removed.

Personal keys are archived when their user is removed from the organization. If the user is re-invited, they need to create new keys; archived keys are not restored.

#How workspaces work

#Haijun Code workspace

#Workspace roles and permissions

#Role inheritance

#Managing workspaces

#Using the Console

#Create a workspace

#Edit workspace details

#Add members to a workspace

#Set workspace limits

#Archive a workspace

#Using the Admin API

#Managing workspace members

#API keys and resource scoping

#Identify the workspace behind an API response

#Workspace limits

#Setting workspace limits

#Usage and cost tracking

#Common use cases

#Environment separation

#Team or department isolation

#Project-based organization

#Best practices

#FAQ

#See also

How workspaces work

Haijun Code workspace

Workspace roles and permissions

Role inheritance

Managing workspaces

Using the Console

Create a workspace

Edit workspace details

Add members to a workspace

Set workspace limits

Archive a workspace

Using the Admin API

Managing workspace members

API keys and resource scoping

Identify the workspace behind an API response

Workspace limits

Setting workspace limits

Usage and cost tracking

Common use cases

Environment separation

Team or department isolation

Project-based organization

Best practices

FAQ

See also