Skip to content
ISHTARR — Confirm minimum read-only OAuth access for workspace billing and usage monitoring
leomessibarca-ops
OP

22 days ago

Hello Railway Support Team,

We are preparing the production launch of our ISHTARR e-commerce website on Railway.

We need to verify the minimum officially supported read-only authorization for an application to monitor workspace-wide billing and resource usage continuously for 30 days.

We want to avoid using an account-admin or workspace-admin credential inside the application.

Could you please confirm:

Does the OAuth scope workspace:viewer permit reading the following GraphQL fields?

workspace.customer.currentUsage

billingPeriod

usageLimit { softLimit hardLimit isOverLimit }

Workspace usage with includeDeleted: true

CPU, memory, network, disk, and backup usage across the workspace

If any of these fields are unavailable to workspace:viewer, which fields are restricted, and what is the least-privileged supported alternative?

Can the supported read-only authorization be maintained for 30 days through offline_access and refresh-token rotation, without repeated administrator intervention?

Is there a supported way to read both current usage and usage limits at the workspace level, including deleted services and projects, without granting mutation permissions?

If OAuth is not supported for these exact fields, is there another official read-only API or integration method suitable for a production monitoring service?

We are not requesting additional resources, billing-limit changes, or administrative access.

We only need confirmation of the supported permissions and token renewal mechanism.

Thank you for your assistance.

ISHTARR LLC

Solved

7 Replies

Railway
BOT

22 days ago

An OAuth token carries the same access as the matching workspace role, capped by the role of the person who authorizes it. With workspace:viewer, your app can read whatever a workspace Viewer can read in the dashboard or API, but nothing more, even if the authorizing user is an admin. The user chooses which workspaces to share on the consent screen. You also need to request email and profile, because workspace queries return empty results without them. See Scopes & User Consent.

We have not confirmed field by field whether a Viewer can read customer.currentUsage, billingPeriod, usageLimit, or usage queries with includeDeleted: true. The way to check is to run those queries with a workspace:viewer token. Any field that needs a higher role will come back not authorized.

For long-running access, request offline_access and include prompt=consent in the authorization request. You'll then get a refresh token along with the access token, and access tokens expire after one hour. The refresh token lets your app get new access tokens without asking the user to authorize again. See Login & Tokens.


Status changed to Awaiting User Response Railway • 22 days ago


Railway

An OAuth token carries the same access as the matching workspace role, capped by the role of the person who authorizes it. With `workspace:viewer`, your app can read whatever a workspace Viewer can read in the dashboard or API, but nothing more, even if the authorizing user is an admin. The user chooses which workspaces to share on the consent screen. You also need to request `email` and `profile`, because workspace queries return empty results without them. See [Scopes & User Consent](https://docs.railway.com/integrations/oauth/scopes-and-user-consent). We have not confirmed field by field whether a Viewer can read `customer.currentUsage`, `billingPeriod`, `usageLimit`, or usage queries with `includeDeleted: true`. The way to check is to run those queries with a `workspace:viewer` token. Any field that needs a higher role will come back not authorized. For long-running access, request `offline_access` and include `prompt=consent` in the authorization request. You'll then get a refresh token along with the access token, and access tokens expire after one hour. The refresh token lets your app get new access tokens without asking the user to authorize again. See [Login & Tokens](https://docs.railway.com/integrations/oauth/login-and-tokens).

leomessibarca-ops
OP

22 days ago

Thank you for the information.

I understand that workspace:viewer is limited to Viewer permissions, and that offline_access supports token renewal.

However, my original question remains unresolved.

Please escalate this request to a human Railway technical support specialist.

Before implementing OAuth in our production application, we need authoritative confirmation of whether workspace:viewer can read these existing GraphQL fields:

  1. customer.currentUsage
  2. billingPeriod
  3. usageLimit { softLimit hardLimit isOverLimit }
  4. Workspace usage with includeDeleted: true
  5. Workspace-wide CPU, memory, network, disk, and backup usage.

For each field, please confirm whether Viewer access is sufficient. If not, specify the minimum supported permission and whether a read-only alternative exists.

Also, please confirm whether offline_access with refresh-token rotation supports uninterrupted authorization for 30 days, and any refresh-token expiration or revocation conditions.

We are specifically trying to avoid placing account-admin or workspace-admin credentials inside our production application.

We are not requesting new resources, administrative privileges, or billing changes.

A field-by-field answer or an official technical reference would resolve this request.

Thank you.

ISHTARR LLC


Status changed to Awaiting Railway Response Railway • 22 days ago


Railway
BOT

22 days ago

On token renewal: access tokens expire after one hour. With offline_access and prompt=consent, you also get a refresh token, so 30 days of continuous access works without anyone signing in again, as long as your app keeps refreshing. Refresh tokens rotate. Always store the refresh_token from your most recent token response, even if it looks unchanged. Each new refresh token is valid for one year from when it was issued. Using an old, already-rotated refresh token revokes the whole authorization immediately, and the user then has to authorize again. Each authorization can hold at most 100 refresh tokens. Past that, the oldest are revoked automatically, so refresh with your existing token instead of re-running the full OAuth flow. See Login & Tokens and Troubleshooting.

On permissions: workspace:viewer gives your app exactly what a workspace Viewer can do in the dashboard or API, never more. It also needs the email and profile scopes, or workspace queries come back empty (Scopes & User Consent). We can't yet give you a confirmed field-by-field list of which of customer.currentUsage, billingPeriod, usageLimit, includeDeleted usage queries and per-resource usage a Viewer can read. Any field that needs a higher role returns a not-authorized error, so a test query with a workspace:viewer token will show you exactly where the limit is. None of these are mutations, so reading them never requires write scopes. If a field does need more than Viewer, that higher scope would also give your app write access in that workspace.


Status changed to Awaiting User Response Railway • 22 days ago


Railway

On token renewal: access tokens expire after one hour. With `offline_access` and `prompt=consent`, you also get a refresh token, so 30 days of continuous access works without anyone signing in again, as long as your app keeps refreshing. Refresh tokens rotate. Always store the `refresh_token` from your most recent token response, even if it looks unchanged. Each new refresh token is valid for one year from when it was issued. Using an old, already-rotated refresh token revokes the whole authorization immediately, and the user then has to authorize again. Each authorization can hold at most 100 refresh tokens. Past that, the oldest are revoked automatically, so refresh with your existing token instead of re-running the full OAuth flow. See [Login & Tokens](https://docs.railway.com/integrations/oauth/login-and-tokens) and [Troubleshooting](https://docs.railway.com/integrations/oauth/troubleshooting). On permissions: `workspace:viewer` gives your app exactly what a workspace Viewer can do in the dashboard or API, never more. It also needs the `email` and `profile` scopes, or workspace queries come back empty ([Scopes & User Consent](https://docs.railway.com/integrations/oauth/scopes-and-user-consent)). We can't yet give you a confirmed field-by-field list of which of `customer.currentUsage`, `billingPeriod`, `usageLimit`, `includeDeleted` usage queries and per-resource usage a Viewer can read. Any field that needs a higher role returns a not-authorized error, so a test query with a `workspace:viewer` token will show you exactly where the limit is. None of these are mutations, so reading them never requires write scopes. If a field does need more than Viewer, that higher scope would also give your app write access in that workspace.

leomessibarca-ops
OP

22 days ago

Thank you. The OAuth token renewal information is now clear.

However, the central permission question remains unanswered.

Please escalate this case to a human technical support specialist.

We need confirmation whether workspace:viewer can read the specified workspace-wide billing and usage fields, including currentUsage, billingPeriod, usageLimit, and usage(includeDeleted: true).

If Viewer access is insufficient, please confirm whether Railway offers an officially supported read-only alternative that does not grant mutation permissions.

We do not need another general explanation of OAuth token renewal.

Thank you.

ISHTARR LLC


Status changed to Awaiting Railway Response Railway • 22 days ago


Railway
BOT

22 days ago

In a workspace, billing and usage, including usage limits, are available only to Admins. Members and Viewers don't have access to them. An OAuth scope grants exactly what that role can do in the dashboard or API, so workspace:viewer is not sufficient for customer.currentUsage, billingPeriod, usageLimit { softLimit hardLimit isOverLimit }, workspace usage with includeDeleted: true, or the workspace-wide CPU, memory, network, disk and backup usage. See Scopes & User Consent.

The minimum permission for these fields is workspace Admin, which means the workspace:admin scope. That scope also gives your application write access to the workspace, not just read access.


Status changed to Awaiting User Response Railway • 22 days ago


Status changed to Solved leomessibarca-ops • 22 days ago


Railway

In a workspace, billing and usage, including usage limits, are available only to Admins. Members and Viewers don't have access to them. An OAuth scope grants exactly what that role can do in the dashboard or API, so `workspace:viewer` is not sufficient for `customer.currentUsage`, `billingPeriod`, `usageLimit { softLimit hardLimit isOverLimit }`, workspace `usage` with `includeDeleted: true`, or the workspace-wide CPU, memory, network, disk and backup usage. See [Scopes & User Consent](https://docs.railway.com/integrations/oauth/scopes-and-user-consent). The minimum permission for these fields is workspace Admin, which means the `workspace:admin` scope. That scope also gives your application write access to the workspace, not just read access.

leomessibarca-ops
OP

22 days ago

Thank you for clarifying.

I understand that workspace:viewer cannot access workspace billing and usage, while workspace:admin includes write permissions.

Before we close this case, please have a human technical specialist confirm one remaining question:

Does Railway offer any officially supported read-only method for obtaining workspace-wide billing, usage limits, billing period, and resource consumption without granting workspace write permissions?

If not, please explicitly confirm that no such read-only authorization is currently supported.

This information is needed for a production security and launch decision.

Thank you.

ISHTARR LLC


Status changed to Awaiting Railway Response Railway • 22 days ago


Railway
BOT

22 days ago

We don't offer a read-only token type for the API. The supported methods are account tokens, workspace tokens, project tokens and OAuth, as listed in the Public API docs. Of those, a workspace token should be treated as equivalent to workspace admin access (Access groups), and an account token can do anything its owner is authorized to do. Project tokens are scoped to a single environment within a project.

So none of these gives you read-only access to workspace-wide billing, usage limits, billing period and resource consumption. Reading that data means granting a credential that can also make changes in the workspace.


Status changed to Awaiting User Response Railway • 22 days ago


Railway
BOT

15 days ago

This thread has been marked as solved automatically due to a lack of recent activity. Please re-open this thread or create a new one if you require further assistance. Thank you!

Status changed to Solved Railway • 15 days ago


Welcome!

Sign in to your Railway account to join the conversation.

Loading...