Access Management
Unlike traditional engines that rely on external systems for access control, 3dverse has built-in permission management. Every action within the platform requires explicit authentication and authorization, ensuring that only approved users can access or modify resources.
If you want your application to have multiple users with different levels of access, you need to understand how 3dverse manages identities and permissions.
Access management is crucial for maintaining the integrity and security of your projects. This guide explains how users, permissions, and tokens work in 3dverse, with a focus on how access is controlled inside environments and when using the API.
Users
A user in 3dverse is basically an identity that can own and manipulate assets within a specific environment. It is the subject that the platform and API recognize when evaluating permissions and recording actions.
A user is represented by a simple pair:
- user_id
- username
It is entirely up to you to decide how to manage users. They could be a human (the identities of someone using your application) or a backend service of one of your applications.
Why Users Matter
-
Only a user can act on assets via the API. Every open, modify, or delete operation is attributed to a user.
-
Permissions are evaluated for users. Access is granted to users on folders (and therefore the assets they contain).
Collaborators vs Users
- Collaborators are people invited to the 3dverse console (at the organization/project level) with roles like Viewer, Editor, Admin.
- Users are the environment-scoped identities the API understands.
When a collaborator uses the console (e.g., opens a scene from the asset browser), 3dverse automatically attaches a user identity to that collaborator’s session. That user is then used to open/edit assets. The user’s effective permissions are derived from the collaborator’s console permissions.
User Roles on Folders
Users have roles that determine their access to folders (and therefore the assets inside).
| Role | Permissions |
|---|---|
| Guest | Can list and read assets, but cannot modify or delete them. |
| Contributor | Can create and modify assets but cannot delete them. |
| Owner | Full permissions, including deletion of assets and managing user access. |
- Permissions are granted on folders.
- They propagate to subfolders and their contents by default.
- If the Direct Access option is set on a subfolder, propagation stops at that subfolder.
- Alice is a Contributor on the folder
/Models. - She can add or update assets in
/Modelsand all its subfolders. - If
/Models/Charactershas another Access set with Alice as Guest, she will only be able to read assets in that subfolder.
Relationship Between Collaborators and Users
When you use the console, you act as a collaborator with a specific role (Viewer, Editor, or Admin) at the organization, project, or environment level.
Whenever you interact with an environment (to create or edit an asset for example), 3dverse transparently assigns a corresponding user identity within that environment to represent your actions.
Collaborator roles are mapped to User roles.
| Collaborator Role | Mapped User Role | Permissions |
|---|---|---|
| Viewer | Guest | Can view assets but cannot modify or delete them. |
| Editor | Contributor | Can create and modify assets, but not delete. |
| Admin | Owner | Full permissions, including deletion and access management. |
This ensures a unified model: at the API level, everything is done by a user.
Groups
Groups make it easier to manage permissions when you have many users.
- Groups exist only at the environment level.
- A group can be granted roles on folders just like a user.
- You assign a role to the group, and every member of the group automatically inherits that role.
If you create a group called "Design Reviewers" with the Guest role, anyone you add to that group will have read-only access to the designated folders.
Using the API with Users
To interact with the API, a user must be authenticated. There are three main ways:
User Token
- A JWT token linked to a specific user.
- Can be generated from the console or programmatically via the API.
- Reflects the roles assigned to that user on folders.
- Typically has a short expiration (max 24 hours) for security.
- Is not revocable (it expires automatically).
Whenever a end user logs into your application, you can generate a user token for them to access assets via the API.
Public Token
- Represents the public user of an environment.
- Each environment has one public user created automatically.
- By default, this user has Guest permissions on the Public folder.
- Useful for sharing assets with end users without creating dedicated accounts for each.
- Does not expire but can be revoked at any time.
If you want to make preview assets available on a website, use the public token for that environment.
API Key
A special type of token linked to a service user with full access to an environment. Typically used by backends or automation systems that need unrestricted access.
It can only be created and named via the console. From here you can also set an optional expiration date and revoke it at any time.
When you want to register a new user to your application and assign them assets, use an API key to perform these operations securely from your backend.
Best Practices
-
Use User Tokens for Individuals: Ideal for users whose actions need to be tracked.
-
Use Public Tokens for Distribution: Perfect for serving assets to anonymous end users.
-
Restrict API Keys: Treat API keys as sensitive secrets and limit their usage to secure backend services.
-
Prefer Least Privilege: Assign the minimum role needed (e.g., Guest instead of Contributor) to reduce risks.
Access tokens at a glance
| Mechanism | Scope | Permissions | Expiration | Revocable | Typical Use Case |
|---|---|---|---|---|---|
| Public Token | Public folder of an environment | Read-only access to public folders and their assets | Never | ✅ Yes | Client-side apps (safe to embed in web clients) |
| User Token | Tied to a specific environment user | Reflects that user’s roles on folders | Max 24h (always expires) | ❌ No | Temporary client access as the user |
| API Key | Entire environment (server-side) | Defined by environment scope | Optional (can be set or never) | ✅ Yes | Pipelines, backend automation |