Upgrade to 0.25

In 0.25 access comes from roles you define, made of granular permissions, and API tokens can be limited to permissions, projects and a date. Everyone keeps the project access they had. Three things stop working unless you act: members creating projects, members with no project creating tokens, and scripts that create tokens or set project members.

At a glance


Upgrade from	Any 0.24.x
Downtime	One server restart
Database	Three migrations. The main one turns `project_members` into `roles`, `role_permissions` and `role_assignments`; the others add columns to `invitations`. At the first start the server hashes every stored API token
Going back	Needs the backup you take before upgrading. See Going back
Needs a decision	Who may create projects from now on

Before you upgrade

Take a backup, as in Upgrade to 0.15. Tokens cannot be unhashed, so the backup is the only way back with them intact.

Copy any token you only keep in the dashboard. After the upgrade Rustrak cannot show a token’s value again. Tokens already in your CI keep working.

What changes

Project roles become editable roles

Each project level in use becomes an ordinary role, under Settings → Roles. Rename, edit or delete them like any other.

Before	After
Project Viewer	Role Viewer, view on every project resource
Project Editor	Role Editor: Viewer, plus changing issues, releases, source maps, alert rules, monitors, project settings and the repository link
Project Admin	Role Project Admin: Editor, plus managing members and deleting the project

Only levels someone holds are created. Each person keeps the same level on the same projects. All three roles also get api-tokens:create, so their holders can still create tokens.

Instance admins are now shown as Owner and keep full access. The API still says admin, and so does OIDC_ADMIN_GROUPS. Instance members stay members.

A new install ships no roles at all. See Roles & Permissions.

Who may create projects

What changed. Any signed-in user could create a project and became its admin. Now it takes projects:create, which no migrated role includes, plus at least one project permission. The creator’s own roles extend to the new project; nobody becomes its admin.

What to do. If members create projects, add Projects with Create to a role under the Workspace tab, or give it as custom permissions. Owners need nothing.

Who may create API tokens

What changed. Creating a token takes api-tokens:create. A member with no project role has no permission to hold, so they can no longer create one. Their existing tokens keep working.

What to do. Give those members a role that includes it, if they need new tokens.

API tokens

What changed.

Tokens are stored as a SHA-256 hash. GET /api/tokens/{id} and the token list show the first 8 characters, as token_prefix. Only the response that creates a token shows its value.
Existing tokens keep full access, limited to what their owner holds.
A token can no longer create tokens. POST /api/tokens needs a signed-in session and answers 403 otherwise.
The MCP tool create_token is gone.
POST /api/tokens refuses permissions its caller does not hold.

What to do. If a script creates tokens with a token, create them once from the dashboard instead and store them. To limit an existing token, replace it: limits are set at creation.

Other API changes

Who is affected. Scripts and tools that call these endpoints, and anything built on @rustrak/client.

Endpoint	Before	Now
`PUT /api/projects/{id}/members`	`{"user_id": 2, "role": "editor"}`	`{"user_id": 2, "role_ids": [2]}`
`GET /api/projects/{id}/members`	One `role` per member	A list of roles per member
`DELETE /api/invitations/{id}`	Took the invitation token	Takes the invitation `id`
`GET /api/projects`, `GET /api/projects/{id}`	Always returned `sentry_key` and `dsn`	Empty without `client-keys:read`

Team, invitation, storage, telemetry, GitHub and MCP settings endpoints used to require an instance admin. Each now checks its own permission, so a member with the right role passes. New endpoints: /api/roles, /api/users/{id}/assignments, /api/access/catalog and /api/access/me.

After you upgrade

Open Settings → Roles: you should see the roles above, with their assignment counts.
Open a member under Settings → Members: Access lists their roles and projects.
Run a job that uses a token, such as a source map upload.

The server log says how many tokens it hashed: Hashed N API token(s) stored before tokens were hashed.

Going back

Stop the server, restore the backup you took before upgrading, and start your previous image, as in Upgrade to 0.15. Whatever changed since the upgrade is lost, including roles and new tokens.