Resources

Users

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

Relations:

• A user belongs to one organization, which handles billing for the user. If the user doesn’t belong to an organization, a “personal” organization is automatically and transparently created for the user with the same name as the user‘s username.
• A user has many (zero or more) secrets.

Access management:

• A user can be granted access to an organization.
• A user can be granted access to a project.

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

CLI: (Not available)

Organizations

Definition: An organization is the top-level owner of users 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:

• An organization has many (one or more) users. Since all users must belong to an organization, when a user is created, they’re added to a “personal” organization that is automatically and transparently created with the same name as the username.
• An organization has many (zero or more) projects.

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 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 and services. You can think of them like repositories in Git.

Relations:

• A project belongs to one organization.
• A project has many (zero or more) streams.
• An project has many (zero or more) services.

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 edit streams and services 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:

• A stream belongs to one project.
• A stream has many (zero or more) stream instances.

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: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:

• A stream instance belongs to one stream.

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

Console: Go to https://beneath.dev/ORGANIZATION/PROJECT/stream: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:

• A service belongs to one project, whose owner handles billing for the service.
• A service has many (zero or more) secrets.

Access management:

• A service can be granted access to a stream.

Console: Go to https://beneath.dev/ORGANIZATION/PROJECT/service: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:

• A secret belongs to either a user or a service.

Access management:

• A user can create secrets for themself.
• A user can create secrets for services that belong to a project that they have admin permissions on.

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.)