OAuth scopes

What it means

An OAuth scope is a named permission a client asks for during authorization. The authorization server presents those names on a consent screen, and the person decides whether to approve the request. The approved scopes are attached to the access token, so the resource server can decide whether a call is allowed.

Scopes are not roles or account levels. They describe specific capabilities, such as reading data or making changes. A client should request the smallest set of scopes it needs for the job, because every extra scope expands what the token can do if it is misused. A read-only integration should not ask for write access.

How it works

During the authorization request, the client includes the scope names it wants. The authorization server shows the consent screen, then issues a token whose grant is limited to what the person approved. The client sends that token with API calls; if a call needs a scope the token lacks, the server should reject it with an authorization error rather than perform the operation.

Scope approval and authentication are separate. A valid token proves the client has a grant, but the scopes on that token still limit what it can do. When a token expires or is refreshed, the new token keeps the same scope grant unless the client asks for less or the authorization server applies its own policy.

How OneLifeVibe uses it

The OneLifeVibe connector uses the scopes olv.read (read only) and olv.write (make the changes the write tools describe), plus openid, profile, email and offline_access. A connection that only needs to read should request only olv.read, not olv.write.

The person sees a consent screen listing what the assistant may do with the connection. Treat that screen as the contract: the approved scopes define the boundary for the connector's calls, and a read-only connection should stay at olv.read from the start.

Common mistakes

Requesting olv.write for a connection that only reads is the most common mistake. It is not least privilege. Another is treating a scope as a role: olv.read does not imply olv.write, and approving one scope does not approve every scope in the client's configuration.

Developers also forget that the consent screen is part of the flow. If the requested scope is missing from the approved grant, the token will not carry it, and write calls should fail even if the client code is otherwise correct. Check the approved scopes before debugging the request body or tool arguments.

Scope strings are exact identifiers. olv.read and olv.write are not interchangeable, and casing matters.