Skip to content
CEagle

Permissions and scopes

The console asks for permissions. The token carries scopes. They are two vocabularies for one thing, and the distinction matters when you read a token.

CEagle has two words for what an application is allowed to do, and they are not interchangeable.

Permissionwhat a person sees

A named, described thing on the consent screen. This is what you ask for when registering an application.

Scopewhat a token carries

The OAuth scope string. One permission expands into one or more of these.

Ask for permissions. Expect scopes.

The catalog#

curl -s https://account.ceagle.cc/api/v1/permissions
{
  "permissions": [
    {
      "key": "profile",
      "name": "Your profile",
      "description": "Your username and display name.",
      "scopes": ["openid", "profile"],
      "required": false
    }
  ]
}
Fields
key

What goes in the permissions array when registering an application.

name

What the consent screen shows.

description

What granting it lets the application do.

scopes

The OAuth scopes this permission expands to.

required

True when every application gets it whether it asks or not.

The endpoint is public and unauthenticated, because a client needs it before anybody has signed in. The console draws its permission picker from the same list, so what you choose there is exactly what the consent screen will show.

The ones you will use#

Common scopes
openidRequired

Required for OpenID Connect. Asks for an id token. Without it you get an access token and no claims about who the person is.

profile

The username and display name.

email

The email address, and whether it has been verified.

offline_access

A refresh token, so the session outlives one access token.

Ask for less#

The consent screen shows what you asked for, and people decline applications that ask for more than they obviously need.

  1. Do you need to know who they are?

    openid. Almost always yes.

  2. Do you need to display their name?

    profile. Not needed if you only ever key on the subject.

  3. Do you need to email them?

    email. Not needed to identify them.

  4. Do you act on their behalf while they are away?

    offline_access. Not needed for a session that ends when the tab closes.

Granted is not requested#

The token response carries a scope field, and it is what was granted, which may be fewer scopes than you asked for.

{ "scope": "openid profile" }

Read it. Do not assume that because you asked for email you got it. A call to the userinfo endpoint filters claims to what the token actually carries, so a missing email claim is a scope problem rather than an account problem.

Changing what an application asks for#

Edit the application in the console. The permission list you save replaces the previous one.

People who consented under the old list are not automatically re-prompted, so widening the list means existing tokens keep their old scopes until the person consents again. Narrowing takes effect for new grants only.

CEagle documentation