Class: IamScopesClient

Defined in: src/iam/scopes-client.ts:54

Client for Strata Cloud Manager IAM scopes (/iam/v1/scopes).

A scope is the SCM role-scope object that an AI Gateway workspace's scope_name points at. SCM's own UI provisions a workspace in three steps, and this client covers the IAM half:

1. iamScopes.create({ name }) — the scope must exist before the workspace.
2. workspaces.create({ name, scope_name }) — returns the workspace slug.
3. iamScopes.bindWorkspace(name, slug) — PUT the scope back with the workspace as a resource.

AIGatewayWorkspacesClient.provision runs all three. Creating a workspace against a scope that does not exist yet is rejected with 400 AB01.

Same OAuth credentials and x-tsg-id header as the AI Gateway admin plane. The caller needs a tenant-root admin role; workspace-scoped roles cannot read or write IAM scopes.

Constructors

Constructor

new IamScopesClient(opts): IamScopesClient;

Defined in: src/iam/scopes-client.ts:59

Parameters

Parameter	Type
opts	IamScopesClientOptions

Returns

IamScopesClient

Methods

list()

list(): Promise<objectOutputType<{
  count: ZodNumber;
  items: ZodArray<ZodObject<{
     name: ZodString;
     description: ZodString;
     resources: ZodArray<ZodObject<{
        resource_type: ZodString;
        resource_id: ZodString;
        metadata: ZodOptional<ZodArray<..., ...>>;
      }, "passthrough", ZodTypeAny, objectOutputType<{
        resource_type: ZodString;
        resource_id: ZodString;
        metadata: ZodOptional<...>;
      }, ZodTypeAny, "passthrough">, objectInputType<{
        resource_type: ZodString;
        resource_id: ZodString;
        metadata: ZodOptional<...>;
     }, ZodTypeAny, "passthrough">>, "many">;
     tsg_id: ZodString;
     id: ZodString;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     name: ZodString;
     description: ZodString;
     resources: ZodArray<ZodObject<{
        resource_type: ZodString;
        resource_id: ZodString;
        metadata: ZodOptional<...>;
      }, "passthrough", ZodTypeAny, objectOutputType<{
        resource_type: ...;
        resource_id: ...;
        metadata: ...;
      }, ZodTypeAny, "passthrough">, objectInputType<{
        resource_type: ...;
        resource_id: ...;
        metadata: ...;
     }, ZodTypeAny, "passthrough">>, "many">;
     tsg_id: ZodString;
     id: ZodString;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     name: ZodString;
     description: ZodString;
     resources: ZodArray<ZodObject<{
        resource_type: ZodString;
        resource_id: ZodString;
        metadata: ZodOptional<...>;
      }, "passthrough", ZodTypeAny, objectOutputType<{
        resource_type: ...;
        resource_id: ...;
        metadata: ...;
      }, ZodTypeAny, "passthrough">, objectInputType<{
        resource_type: ...;
        resource_id: ...;
        metadata: ...;
     }, ZodTypeAny, "passthrough">>, "many">;
     tsg_id: ZodString;
     id: ZodString;
  }, ZodTypeAny, "passthrough">>, "many">;
}, ZodTypeAny, "passthrough">>;

Defined in: src/iam/scopes-client.ts:83

List every IAM scope in the tenant. Not paginated in observed traffic (count equals items.length). Verified live 2026-09-11.

A scope with an empty resources array is not bound to any workspace — typically the leftover of a provisioning run that failed between steps 1 and 2.

Returns

Promise<objectOutputType<{ count: ZodNumber; items: ZodArray<ZodObject<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<..., ...>>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<...>; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<...>; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, "passthrough", ZodTypeAny, objectOutputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<...>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ...; resource_id: ...; metadata: ...; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ...; resource_id: ...; metadata: ...; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">, objectInputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<...>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ...; resource_id: ...; metadata: ...; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ...; resource_id: ...; metadata: ...; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">>, "many">; }, ZodTypeAny, "passthrough">>

{ count, items }.

Example

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const { items } = await gw.iamScopes.list();
const unbound = items.filter((s) => s.resources.length === 0).map((s) => s.name);
// items[0] => { name: 'main_airs_workspace_1852583913', resources: [{ resource_type: 'workspace', resource_id: 'ws-main-a-349e0e', metadata: [] }], ... }

---

get()

get(name): Promise<objectOutputType<{
  name: ZodString;
  description: ZodString;
  resources: ZodArray<ZodObject<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
  }, ZodTypeAny, "passthrough">>, "many">;
  tsg_id: ZodString;
  id: ZodString;
}, ZodTypeAny, "passthrough">>;

Defined in: src/iam/scopes-client.ts:108

Fetch one scope by name (the id field, name:tsg, is not a valid key). Verified live 2026-09-11.

Parameters

Parameter	Type	Description
name	string	Scope name, e.g. ws_production_bx7qw0.

Returns

Promise<objectOutputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">>

Example

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const scope = await gw.iamScopes.get('ws_production_bx7qw0');
// scope.resources[0].resource_id => 'ws-produc-985697' (the workspace slug)

---

create()

create(input): Promise<objectOutputType<{
  name: ZodString;
  description: ZodString;
  resources: ZodArray<ZodObject<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
  }, ZodTypeAny, "passthrough">>, "many">;
  tsg_id: ZodString;
  id: ZodString;
}, ZodTypeAny, "passthrough">>;

Defined in: src/iam/scopes-client.ts:141

Create a scope. Step 1 of workspace provisioning — run it before workspaces.create(), which rejects an unknown scope_name with 400 AB01.

Mirrors SCM's captured request (2026-09-11): description defaults to '' and resources to []; the workspace is bound afterwards with IamScopesClient.bindWorkspace.

Parameters

Parameter	Type	Description
input	IamScopeCreateInput	name is required and must be unique in the tenant.

Returns

Promise<objectOutputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">>

The created scope. id is ${name}:${tsg_id}.

Example

import { AIGatewayClient, generateWorkspaceScopeName } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const scope = await gw.iamScopes.create({
  name: generateWorkspaceScopeName('Truffles'), // 'ws_truffles_ggolfu'
  description: 'Online recipe generation application',
});
// scope => { name: 'ws_truffles_ggolfu', description: '...', resources: [], tsg_id: '1001464285', id: 'ws_truffles_ggolfu:1001464285' }

---

update()

update(name, input): Promise<objectOutputType<{
  name: ZodString;
  description: ZodString;
  resources: ZodArray<ZodObject<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
  }, ZodTypeAny, "passthrough">>, "many">;
  tsg_id: ZodString;
  id: ZodString;
}, ZodTypeAny, "passthrough">>;

Defined in: src/iam/scopes-client.ts:180

Replace a scope's description and resources. Full replacement (PUT), not a patch: omit resources and the scope ends up bound to nothing. Prefer IamScopesClient.bindWorkspace to add a workspace without dropping the others.

Mirrors SCM's captured request (2026-09-11), which repeats name in the body; this method copies it from the path.

Parameters

Parameter	Type	Description
name	string	Scope name (path key).
input	IamScopeUpdateInput	Fields to write. Missing fields are sent as '' / [].

Returns

Promise<objectOutputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">>

Example

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

await gw.iamScopes.update('ws_truffles_ggolfu', {
  description: 'Online recipe generation application',
  resources: [{ resource_type: 'workspace', resource_id: 'ws-truffl-03e7d9' }],
});

---

bindWorkspace()

bindWorkspace(name, workspaceSlug): Promise<objectOutputType<{
  name: ZodString;
  description: ZodString;
  resources: ZodArray<ZodObject<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     resource_type: ZodString;
     resource_id: ZodString;
     metadata: ZodOptional<ZodArray<ZodUnknown, "many">>;
  }, ZodTypeAny, "passthrough">>, "many">;
  tsg_id: ZodString;
  id: ZodString;
}, ZodTypeAny, "passthrough">>;

Defined in: src/iam/scopes-client.ts:221

Bind a workspace to a scope. Step 3 of workspace provisioning.

Reads the scope, appends { resource_type: 'workspace', resource_id: slug } unless an identical binding is already present, and PUTs the result — so existing bindings survive and re-running after a partial failure is safe. For a freshly created scope the resulting body is byte-for-byte the request SCM's UI sends.

Parameters

Parameter	Type	Description
name	string	Scope name.
workspaceSlug	string	The workspace slug (ws-truffl-03e7d9) from workspaces.create(). Not the UUID: SCM binds by slug.

Returns

Promise<objectOutputType<{ name: ZodString; description: ZodString; resources: ZodArray<ZodObject<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, "passthrough", ZodTypeAny, objectOutputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">, objectInputType<{ resource_type: ZodString; resource_id: ZodString; metadata: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">>, "many">; tsg_id: ZodString; id: ZodString; }, ZodTypeAny, "passthrough">>

The updated scope.

Example

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const ws = await gw.workspaces.create({ name: 'Truffles', scope_name: 'ws_truffles_ggolfu' });
const scope = await gw.iamScopes.bindWorkspace('ws_truffles_ggolfu', ws.slug);
// scope.resources => [{ metadata: [], resource_id: 'ws-truffl-03e7d9', resource_type: 'workspace' }]

---

delete()

delete(name): Promise<void>;

Defined in: src/iam/scopes-client.ts:258

Delete a scope by name.

Not live-verified — SCM's UI was not observed deleting a scope, and no scope in the verification tenant could be sacrificed. The route follows the resource's REST shape; treat a 405 or 404 as the API declining rather than as an SDK bug. Used by AIGatewayWorkspacesClient.provision to roll back a scope it created when the workspace step fails.

Parameters

Parameter	Type	Description
name	string	Scope name.

Returns

Promise<void>

Example

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

await gw.iamScopes.delete('ws_truffles_ggolfu');