Resources

An overview of every resource that can be created and managed in Beneath

Users

Definition: A user represents a real person who operates on Beneath.

Relations:

Access management:

Console: Go to https://beneath.dev/USERNAME

CLI: (Not available)

Organizations

Definition: An organization is the top-level owner of users, services and projects. Billing is managed at the organization level, which means that every resource that can accrue bills is directly or indirectly linked to exactly one organization.

Relations:

Access management:

  • A user can access an organization.
    • The view permission grants the user permission to browse the members and projects in the organization.
    • The create permission grants the user permission to create and manipulate projects and services in the organization.
    • The admin permission grants the user permission to add and delete members, monitor members’ usage, and to change billing information.

Console: Go to https://beneath.dev/ORGANIZATION

CLI: Run beneath organization --help for details.

Projects

Definition: A project is a collection of streams. You can think of them like repositories in Git.

Relations:

Access management:

  • A user can access a project.
    • The view permission grants the user permission to browse the contents of the project, including viewing and querying records in its streams.
    • The create permission grants the user permission to create and delete streams in the project, including writing data directly to (non-derived) streams.
    • The admin permission grants the user permission to add, remove and change permissions for other users.

Console: Go to https://beneath.dev/ORGANIZATION/PROJECT

CLI: Run beneath project --help for details.

Streams

Definition: A stream is the prototype of a collection of records with a common schema. For more information about streams and the related stream instances, see Streams.

Relations:

Access management:

  • A user can access a stream through its permissions for the parent project.
    • The view permission on project grants permission to view and query records.
    • The create permission on project grants permission to write records.
  • A service can access a stream. (Note the difference: services have direct permissions for a stream, while users get indirect permissions on a project-level)
    • The read permission grants the service permission to read and query records.
    • The write permission grants the service permission to write records.

Console: Go to https://beneath.dev/ORGANIZATION/PROJECT/STREAM

CLI: Run beneath stream --help for details.

Stream instances

Definition: A stream instance represents a single version of a stream. For more information, see Streams.

Relations:

Access management: A stream instance inherits the permissions of its parent stream.

Console: Go to https://beneath.dev/ORGANIZATION/PROJECT/STREAM (only shows the primary stream instance)

CLI: Run beneath stream instance --help for details.

Services

Definition: A service represents a system with access to read or write data to Beneath. You can think of a service as a user for your code. They’re especially useful for creating secrets that you can use in your code to read and write to Beneath in a safe way.

A service has the following properties:

  • You grant it custom access permissions (on a stream level) that are not tied to the permissions of a specific user
  • You can create secrets for the service, which you embed in your code to use Beneath
  • You get usage metrics (reads and writes) for the service
  • You can set usage limits (reads and writes) for the service on a monthly basis
  • You have to explicitly grant permissions to access public streams (unlike users, which automatically have access to public streams)

Relations:

Access management:

Console: Go to https://beneath.dev/beneath/-/services/SERVICE

CLI: Run beneath service --help for details.

Secrets

Definition: A secret is a token that you can use to authenticate to Beneath (some products call it an API token). It belongs to either a user or a service. When you authenticate with a secret, you get the same access permissions as the parent user or service (with the caveat that you can create special read-only secrets for a user).

If you need to expose a secret publicly (e.g. in your front-end code), make sure it belongs to a service with sensible usage quotas and only read-only permissions.

Relations:

Access management:

Console: For user-owned secrets, go to https://beneath.dev/USERNAME/-/secrets. (Not available for service-owned secrets.)

CLI: For service-owned secrets, run beneath service --help for details. (Not available for user-owned secrets.)