Account and Basins

Account and basin operations manage the lifecycle of your S2 resources: creating and configuring basins (which are namespaces, or large collections of streams), managing streams, and issuing access tokens. These map directly to the corresponding REST API endpoints, so the API reference is a particularly good companion to this page.

Basins

Basins are containers for streams, similar to buckets in object storage. Each basin belongs to an account and has its own configuration for default stream settings, which will be used when creating new streams unless explicitly overridden.

TypeScript
Go
Rust

// List basins
const basins = await client.basins.list();

// Create a basin
await client.basins.create({ basin: "my-events" });

// Get configuration
const config = await client.basins.getConfig({ basin: "my-events" });

// Delete
await client.basins.delete({ basin: "my-events" });

// List basins
basins, _ := client.Basins.List(ctx, nil)

// Create a basin
client.Basins.Create(ctx, s2.CreateBasinArgs{Basin: "my-events"})

// Get configuration
config, _ := client.Basins.GetConfig(ctx, "my-events")

// Delete
client.Basins.Delete(ctx, "my-events")

// List basins
let basins = client.list_basins(ListBasinsInput::new()).await?;

// Create a basin
client
    .create_basin(CreateBasinInput::new("my-events".parse()?))
    .await?;

// Get configuration
let config = client.get_basin_config("my-events".parse()?).await?;

// Delete
client
    .delete_basin(DeleteBasinInput::new("my-events".parse()?))
    .await?;

See basin configuration for details on available options.

Streams

Streams live within basins and are the core data structure in S2. You can have an unlimited amount of streams, and create them instantly (even on first use). Data retention policies (e.g. TTL-based trimming), storage classes, timestamping behavior, are all configurable.

TypeScript
Go
Rust

// List streams
const streams = await basin.streams.list({ prefix: "user-" });

// Create a stream
await basin.streams.create({
	stream: "user-actions",
	config: {
		/* optional configuration */
	},
});

// Get configuration
const streamConfig = await basin.streams.getConfig({ stream: "user-actions" });

// Delete
await basin.streams.delete({ stream: "user-actions" });

// List streams
streams, _ := basin.Streams.List(ctx, &s2.ListStreamsArgs{Prefix: "user-"})

// Create a stream
basin.Streams.Create(ctx, s2.CreateStreamArgs{
	Stream: "user-actions",
	Config: &s2.StreamConfig{ /* optional */ },
})

// Get configuration
config, _ := basin.Streams.GetConfig(ctx, "user-actions")

// Delete
basin.Streams.Delete(ctx, "user-actions")

// List streams
let streams = basin
    .list_streams(ListStreamsInput::new().with_prefix("user-".parse()?))
    .await?;

// Create a stream
basin
    .create_stream(CreateStreamInput::new("user-actions".parse()?))
    .await?;

// Get configuration
let config = basin.get_stream_config("user-actions".parse()?).await?;

// Delete
basin
    .delete_stream(DeleteStreamInput::new("user-actions".parse()?))
    .await?;

See stream configuration for more details on all options.

Access Tokens

Access tokens control what a client can do. Each token has a scope that restricts which basins and streams it can access, and what operations it can perform. See the access token API reference for the full specification, including operation groups, granular permissions, and auto-prefixing for multi-tenant setups.

TypeScript
Go
Rust

// List tokens (returns metadata, not the secret)
const tokens = await client.accessTokens.list();

// Issue a token scoped to streams under "users/1234/"
const { accessToken: issuedToken } = await client.accessTokens.issue({
	id: "user-1234-rw-token",
	scope: {
		basins: { prefix: "" }, // all basins
		streams: { prefix: "users/1234/" },
		opGroups: { stream: { read: true, write: true } },
	},
	expiresAt: new Date("2027-01-01"),
});

// Revoke a token
await client.accessTokens.revoke({ id: "user-1234-rw-token" });

// List tokens (returns metadata, not the secret)
tokens, _ := client.AccessTokens.List(ctx, nil)

// Issue a token scoped to streams under "users/1234/"
expires := time.Date(2027, 1, 1, 0, 0, 0, 0, time.UTC)
result, _ := client.AccessTokens.Issue(ctx, s2.IssueAccessTokenArgs{
	ID: "user-1234-rw-token",
	Scope: s2.AccessTokenScope{
		Basins:  &s2.ResourceSet{Prefix: s2.String("")}, // all basins
		Streams: &s2.ResourceSet{Prefix: s2.String("users/1234/")},
		OpGroups: &s2.PermittedOperationGroups{
			Stream: &s2.ReadWritePermissions{Read: true, Write: true},
		},
	},
	ExpiresAt: &expires,
})

// Revoke a token
client.AccessTokens.Revoke(ctx, s2.RevokeAccessTokenArgs{ID: "user-1234-rw-token"})

// List tokens (returns metadata, not the secret)
let tokens = client.list_access_tokens(Default::default()).await?;

// Issue a token scoped to streams under "users/1234/"
let result = client
    .issue_access_token(
        IssueAccessTokenInput::new(
            "user-1234-rw-token".parse()?,
            AccessTokenScopeInput::from_op_group_perms(
                OperationGroupPermissions::new()
                    .with_stream(ReadWritePermissions::read_write()),
            )
            .with_basins(BasinMatcher::Prefix("".parse()?)) // all basins
            .with_streams(StreamMatcher::Prefix("users/1234/".parse()?)),
        )
        .with_expires_at("2027-01-01T00:00:00Z".parse()?),
    )
    .await?;

// Revoke a token
client
    .revoke_access_token("user-1234-rw-token".parse()?)
    .await?;

Metrics

Metrics are available at three levels: account, basin, and stream. Each returns time-series or scalar data for the specified metric set.

TypeScript
Go
Rust

// Account-level: active basins over the last 30 days
const accountMetrics = await s2.metrics.account({
	set: "active-basins",
	start: new Date(Date.now() - 30 * 24 * 3600 * 1000),
	end: new Date(),
});

// Basin-level: storage usage with hourly resolution
const basinMetrics = await s2.metrics.basin({
	basin: "events",
	set: "storage",
	start: new Date(Date.now() - 6 * 3600 * 1000),
	end: new Date(),
	interval: "hour",
});

// Stream-level: storage for a specific stream
const streamMetrics = await s2.metrics.stream({
	basin: "events",
	stream: "user-actions",
	set: "storage",
	start: new Date(Date.now() - 3600 * 1000),
	end: new Date(),
	interval: "minute",
});

now := time.Now().Unix()
thirtyDaysAgo := now - 30*24*3600
sixHoursAgo := now - 6*3600
hourAgo := now - 3600

// Account-level: active basins over the last 30 days
accountMetrics, _ := client.Metrics.Account(ctx, &s2.AccountMetricsArgs{
	Set:   s2.AccountMetricSetActiveBasins,
	Start: &thirtyDaysAgo,
	End:   &now,
})

// Basin-level: storage usage with hourly resolution
hourInterval := s2.TimeseriesIntervalHour
basinMetrics, _ := client.Metrics.Basin(ctx, &s2.BasinMetricsArgs{
	Basin:    "events",
	Set:      s2.BasinMetricSetStorage,
	Start:    &sixHoursAgo,
	End:      &now,
	Interval: &hourInterval,
})

// Stream-level: storage for a specific stream
minuteInterval := s2.TimeseriesIntervalMinute
streamMetrics, _ := client.Metrics.Stream(ctx, &s2.StreamMetricsArgs{
	Basin:    "events",
	Stream:   "user-actions",
	Set:      s2.StreamMetricSetStorage,
	Start:    &hourAgo,
	End:      &now,
	Interval: &minuteInterval,
})

use std::time::{Duration, SystemTime};

let now = SystemTime::now();
let thirty_days_ago = now - Duration::from_secs(30 * 24 * 3600);
let six_hours_ago = now - Duration::from_secs(6 * 3600);
let hour_ago = now - Duration::from_secs(3600);

// Account-level: active basins over the last 30 days
let account_metrics = s2
    .get_account_metrics(GetAccountMetricsInput::active_basins(thirty_days_ago, now))
    .await?;

// Basin-level: storage usage with hourly resolution
let basin_metrics = s2
    .get_basin_metrics(
        GetBasinMetricsInput::storage("events".parse()?, six_hours_ago, now)
            .with_interval(TimeseriesInterval::Hour),
    )
    .await?;

// Stream-level: storage for a specific stream
let stream_metrics = s2
    .get_stream_metrics(
        GetStreamMetricsInput::storage("events".parse()?, "user-actions".parse()?, hour_ago, now)
            .with_interval(TimeseriesInterval::Minute),
    )
    .await?;

See the metrics API reference for available metric sets and response formats.

SDKs

​Basins

​Streams

​Access Tokens

​Metrics

Basins

Streams

Access Tokens

Metrics