OAuth Scopes

Every OAuth Bearer token carries a set of scopes. A scope is a coarse, user-consentable limit on what the token may do. This page lists the full scope vocabulary, explains how scopes combine, and shows which parts of the API each scope covers.

Scopes only narrow access

A scope can never grant a token more than the user themselves can do. The effective permission on a Bearer request is the intersection of the user's live abilities (the ceiling, set by their roles and groups) and the token's granted scopes (a filter on top). There is deliberately no administrator scope — administrative, configuration, and credential-management operations are never reachable with a Bearer token.

The ceiling itself is also lowered: administrative abilities are dropped from every Bearer request, so connecting as an administrator does not raise it. See Administrators are not privileged over OAuth.

The scope vocabulary

There are 21 scopes: a standalone identity scope, plus a read and a write scope for each of ten data areas. A write scope always includes its matching read scope.

Data area	Read scope	Write scope	What it covers
Identity	jx:identity	(none)	Your own sign-in name and email address, via /userinfo. Never implied by another scope.
Time	jx:time	jx:time:write	Your own time sheets and entries, including entry-sheet notes.
Expenses	jx:expense	jx:expense:write	Your own expense sheets and entries.
Custom	jx:custom	jx:custom:write	Your own custom and mileage entries.
Leave	jx:leave	jx:leave:write	Your own leave requests and accrual balances.
Crew	jx:crew	jx:crew:write	Other users' sheets you oversee (crew entry / timekeeping).
Suggestions	jx:suggestions	jx:suggestions:write	Your Suggested Entries — calendar events and other activity proposed as entries, but not yet entered.
Projects	jx:projects	jx:projects:write	Projects, tasks, and entry codes (the work-breakdown structure), plus project notes.
Resources	jx:resources	jx:resources:write	Assignments, requisitions, and Teams (the "Resources" menu).
Reports	jx:reports	jx:reports:write	Run reports and read dashboard data; write manages report definitions and dashboard layout.
Approvals	jx:approvals	jx:approvals:write	Your approval queue and its items; write approves, rejects, and reopens.
User preferences	jx:user-preferences	jx:user-preferences:write	Your own low-risk settings: UI preferences, favorites, and notifications.

How scopes combine

When a token is issued, a few rules expand the granted scopes. Understanding them helps you request the minimum set your app needs:

• Write includes read. Holding jx:time:write also grants jx:time. You do not need to request both.
• Entry scopes include project read. Any entry scope (jx:time, jx:expense, jx:custom, or jx:leave) also grants read access to the project / task / entry-code catalog (jx:projects read), because you must be able to see chargeable codes to fill out a sheet.
• Reference data rides along. Once a token holds at least one data-area scope, common reference and display data — entry-screen layouts, entry periods, custom-field definitions, timezones, and the display names of associated users, projects, and codes — is readable without a separate scope. (A token holding only jx:identity does not get this reference data.)
• Your own vs. other people's data. The data-area scopes reach only the signed-in user's own sheets. Acting on another user's sheets additionally requires the crew scope — for example, reading another user's time sheet needs jx:time and jx:crew; entering time on their behalf needs jx:time:write and jx:crew:write.
• Suggestions stand apart from time. jx:suggestions:write lets an app propose entries and read back what it proposed. It does not reach the user's sheets or entries — a calendar or ticketing integration can feed suggestions without being trusted to enter time. The reverse implication does hold: the timesheet connection levels include suggestion access, since an app already entering real time is strictly more powerful than one proposing it.
• No administrator scope. There is no scope that unlocks admin, configuration, or credential-management endpoints over a Bearer token.

Administrators are not privileged over OAuth

Administrative abilities are suppressed on every Bearer request, not merely blocked at administrative endpoints. A token issued to an administrator behaves like a token issued to an ordinary user holding only that person's other, explicitly assigned roles.

This is easy to miss, because it shows up on ordinary data endpoints rather than as an error. Where the web interface shows an administrator everyone's data, the same endpoint over OAuth returns only what their non-administrative roles and group memberships reach — which can be nothing at all. The response is a 200 OK with a short or empty results array, not a 403.

If your app needs to reach other people's data, the account that connects it must hold the relevant ability explicitly, through a role, and share the appropriate groups, exactly as a non-administrator would. Reading other people's sheets, for example, needs a real timekeeping role and the right group memberships in addition to jx:crew — being an administrator is not a substitute.

Testing with an admin account

Connecting your app with an administrator account is a common way to get an empty result set and conclude the API is broken. Test with an account that carries the roles a real user of your integration would have.

What each scope covers

Use this as a guide when requesting scopes. In the API Reference, each endpoint that accepts a Bearer token lists its required scope under the endpoint's authorization information.

Scope	Endpoints it covers
jx:identity	/userinfo
jx:time[:write]	Time sheets and time records
jx:expense[:write]	Expense sheets and expense records
jx:custom[:write]	Custom sheets and custom/mileage records
jx:leave[:write]	Leave requests; read also covers accrual balances
jx:crew[:write]	Entering and correcting other users' sheets (crew / timekeeping)
jx:suggestions[:write]	Suggested Entries, including feeding events in from an integration
jx:projects[:write]	Projects and entry codes
jx:resources[:write]	Assignments, requisitions, and teams
jx:reports[:write]	Running reports and report settings
jx:approvals[:write]	The approval queue and approve/reject/reopen actions
jx:user-preferences[:write]	Favorites, per-user UI settings, and notifications

Some scopes have no separate write endpoints

Accrual balances and rate-rule policies are readable with a Bearer token (jx:leave and jx:reports respectively) but their write side is administrative, so it is cookie-only.

Reference reads and the user directory

Reference and "render" data — entry screens, entry columns, entry periods, custom field definitions, screen choices, timezones, and the list of system abilities — is readable by any token that holds at least one data-area scope (see How scopes combine). These endpoints do not require a specific domain scope.

The Users collection is a special case for Bearer tokens: it returns only a directory view — user ID, full name, and active status — regardless of the fields you request. Login names, email addresses, roles, and abilities are never returned to a Bearer token. To read the signed-in user's own email, use /api/v1/userinfo with the jx:identity scope.

Endpoints that require cookie authentication

Some endpoints are never reachable with a Bearer token, regardless of scope. They require session-cookie authentication. Calling them with a Bearer token returns 403 Forbidden with no required scope named. These families are cookie-only by design:

• Session and sign-in plumbing — /api/v1/login, /api/v1/logout, and navigation. (A Bearer token can never create a session.)
• API Key management — creating, listing, searching, and deleting API Keys.
• OAuth app administration — approving, disabling, and managing connected apps, allowed scopes, and consent bundles.
• User administration — creating, updating, deleting, and activating users (reading the user directory is allowed; see above).
• System and configuration — global UI screen settings, geofences, the activity monitor, auto sheet processing, and system integrity.
• Report commit — committing records from the reporting surface.
• Administrative write endpoints — the write side of accruals and rate-rule policies.

For anything on this list, use an API Key with the session-cookie flow.

Consent levels

On the consent screen, users grant scopes by choosing a connection level — a named bundle. See Consent and connection levels on the OAuth page for the built-in levels and how requested scopes map to them.

Site restrictions

An administrator can restrict which scopes may be granted on a site at all (the allowed-scopes list) and can customize the connection levels. If a scope has been removed from the site's allowlist, it is dropped from tokens immediately — including tokens that were already issued — so an integration may see access narrow without a token expiring.