Build on Your Own Workspace

You don’t need a partner account to start building. When you log in with nsc login, the SDKs can use that login to act inside your own workspace, the same way a tenant token acts inside a customer’s tenant. That makes your workspace a good place to develop the parts of your platform that run inside a tenant, such as creating instances or managing revokable tokens. When your partner account is ready, the same code runs in your customers’ tenants. Only the source of the token changes.

Use your nsc login for local development only. In production, your platform issues a tenant token for each customer’s tenant.

Log in

Install the nsc CLI and log in. The browser asks you to pick a workspace. The SDKs act inside the workspace you pick.

nsc login

Create the client

loadDefaults() loads your login, and the client authenticates with it.

import { createIAMClient } from "@namespacelabs/sdk/api/iam";
import { loadDefaults } from "@namespacelabs/sdk/auth";

const tenantClient = createIAMClient({
  tokenSource: await loadDefaults(),
});

import (
	"log"

	"namespacelabs.dev/integrations/api/iam"
	"namespacelabs.dev/integrations/auth"
)

tokens, err := auth.LoadDefaults()
if err != nil {
	log.Fatal(err)
}

tenantClient, err := iam.NewClient(ctx, tokens)
if err != nil {
	log.Fatal(err)
}
defer tenantClient.Close()

The SDK issues short-lived tokens from your login session and renews them automatically, so the client keeps working for as long as you stay logged in.

Test the client

Reading your workspace’s policies is a read-only call, which makes it a safe first request.

const { policies } = await tenantClient.tenants.describePolicies({});

console.log(`Authenticated. Policies found: ${policies.length}.`);

import iamv1beta "namespacelabs.dev/integrations/proto/namespace/cloud/iam/v1beta"

resp, err := tenantClient.Tenants.DescribePolicies(ctx, &iamv1beta.DescribePoliciesRequest{})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Authenticated. Policies found: %d.\n", len(resp.Policies))

The client acts inside the workspace you picked at login, not a customer’s tenant. Anything you create belongs to that workspace and counts toward its usage.

If NSC_TOKEN_FILE is set, loadDefaults() uses that token file instead of your login. Unset it to go back to your login.

Use a development token instead

loadDefaults() works when your code runs on the machine where you logged in. To run it somewhere else, such as a script on another machine or a container, use a development token instead. It acts in the same workspace as your login.

Generate a development token

Run this on the machine where you ran nsc login, because it uses your login.

nsc auth generate-dev-token

The token lasts about an hour and is not renewed, so generate a new one when it expires.

Create the client from the token

Pass the token to the client where your code runs. This example reads it from a NAMESPACE_TOKEN environment variable.

import { createIAMClient } from "@namespacelabs/sdk/api/iam";
import { fromBearerToken } from "@namespacelabs/sdk/auth";

const tenantClient = createIAMClient({
  tokenSource: fromBearerToken(process.env.NAMESPACE_TOKEN!),
});

tenantClient, err := iam.NewClient(ctx, bearerTokenSource(os.Getenv("NAMESPACE_TOKEN")))
if err != nil {
	log.Fatal(err)
}
defer tenantClient.Close()

Your login is the better choice for code that runs on your own machine, because the SDK renews its tokens for you.

What you can build this way

Your login works with every Namespace client, not just IAM, and for everything a tenant token can do. You can build and test:

Running instances, builds, and other workloads.
Using storage, such as cache volumes, the container registry, and secrets.
Reading policies.
Creating, listing, and revoking revokable tokens.

Pass the same token source to any client. For example, a Compute client that lists the instances in your workspace:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";
import { loadDefaults } from "@namespacelabs/sdk/auth";

const compute = createComputeClient({ tokenSource: await loadDefaults() });

const { instances } = await compute.compute.listInstances({});

import (
	"namespacelabs.dev/integrations/api/compute"
	"namespacelabs.dev/integrations/auth"
	computepb "namespacelabs.dev/integrations/proto/namespace/cloud/compute/v1beta"
)

tokens, err := auth.LoadDefaults()
if err != nil {
	log.Fatal(err)
}

computeClient, err := compute.NewClient(ctx, tokens)
if err != nil {
	log.Fatal(err)
}
defer computeClient.Close()

resp, err := computeClient.Compute.ListInstances(ctx, &computepb.ListInstancesRequest{})

Managing tenants needs partner credentials, so your login can’t create, list, update, or delete tenants, set their policies, or issue tenant tokens.

Move to production

In production, your service acts for a customer with a tenant token instead of your login. Your platform issues the token for the customer’s tenant with its partner credentials. Replace loadDefaults() with that token:

import { fromBearerToken } from "@namespacelabs/sdk/auth";

const tenantClient = createIAMClient({
  tokenSource: fromBearerToken(bearerToken),
});

tenantClient, err := iam.NewClient(ctx, bearerTokenSource(bearerToken))

The rest of your code stays the same.

Next steps

Instances quickstart

Run your first instance in your workspace.

Partner credentials

Set up partner credentials to manage tenants.

Build with Namespace

Building Blocks

Log in

Create the client

Test the client

Use a development token instead

Generate a development token

Create the client from the token

What you can build this way

Move to production

Next steps

Instances quickstart

Partner credentials

​Create a client from your login

Log in

Create the client

Test the client

​Use a development token instead

Generate a development token

Create the client from the token

​What you can build this way

​Move to production

​Next steps

Instances quickstart

Partner credentials

Create a client from your login

Use a development token instead

What you can build this way

Move to production

Next steps