S2 supports an unlimited number of revokable access tokens that can be scoped to a set of resources and the operations that are allowed on those resources.

You can issue permanent access tokens for services, or time-bounded ones for ephemeral usage, e.g. for end users to access an S2 stream.

There are 2 ways to list, issue, and revoke access tokens:

Dashboard

REST API

Of course to use the API you will need an access token in the first place!

GET /access-tokens


POST /access-tokens


DELETE /access-tokens/{id}

​
Properties

​
Identifier

Access token IDs must be unique to the account and may be up to 96 bytes in length.

List requests allow prefix filtering, which is handy for namespacing with a delimiter like /. For example, you can name them as user/{user} and service/{service} to easily filter for access tokens for users vs services.

​
Expiration

An expiry time at which the access token becomes immediately invalid.

This is specified as an ISO 8601 timestamp with the REST API.

Expiry time of the requestor’s access token will be the default and maximum possible expiry time when issuing a new token.

Dashboard access does not have an expiry, so permanent access tokens can be issued from there. However, a limited-expiry access token can be used to only issue new access tokens bounded by its own expiry.

​
Scope

​
Resources

Access to the following resources can be scoped:

  • Basins
  • Streams
  • Access tokens

To specify the set of resources for each of these, you can choose either of:

Grant access to all resources with a common prefix:

{ "prefix": "logs/" }

Empty prefix matches all resources (allow all).

When configuring access to streams with a prefix, you can also enable auto-prefixing.

This acts as a transparent logical namespace within a basin:

  • Stream name arguments provided in requests will be automatically prefixed.
  • The prefix will be stripped from a response containing a stream name, such as when listing streams.

​
Operations

There are two complementary ways to authorize operations:

Operation groups provide a high-level way to grant read/write access.

{
  "op_groups": {
    "account": { "read": false, "write": false },
    "basin": { "read": true, "write": false },
    "stream": { "read": true, "write": false }
  }
}

Group-level permissions will also apply to any new operations added to the group.

Both groups and individual operations may be specified together — the effective permissions are a union.