Scopes

Scopes control what actions an application can perform. Each app type has its own scope set.

Least Privilege Principle

Only request the scopes you need. Requesting unnecessary scopes increases security risk and may require additional user consent.

---

M2M Scopes

M2M (Machine-to-Machine) applications use the following scopes to control API access.

Scope	Enum Value
FILE_UPLOAD	EScopes.FileUpload
ON_BOARDING	EScopes.Onboarding
MINTING	EScopes.Minting
AGE_VERIFICATION	EScopes.AgeVerification

M2M Scope Usage

M2M scopes are for server-to-server API access only. They cannot be used for user authentication or login flows.

---

IDP Scopes (OIDC)

IDP applications use OIDC scopes to control what identity information is returned.

Scope	Description	Claims Returned	Required
openid	Required for OIDC	sub	✅ Yes
profile	Basic profile	name, given_name, picture	○ No
email	Email address	email, email_verified	○ No
phone	Phone number	phone_number, phone_number_verified	○ No

---

Hosted UI Scopes

Hosted UI does not use scopes. Access is controlled via the hosted auth flow and token claims.

---

Scope Assignment

Scopes are assigned from the Developer Portal when you create or edit an application:

1. Open Applications in the portal and pick the application.
2. Open the Scopes section.
3. Tick the scopes the application needs (M2M and IDP); Hosted UI does not expose this picker.
4. Save — new tokens issued after the change carry the updated scope set.

See Create application — step-by-step for the full registration walkthrough.

Default Scopes

• IDP: If no scopes provided, defaults to openid, profile, email
• M2M: No default scopes; all scopes must be explicitly assigned
• Hosted UI: No scopes applicable

---

Scope Definitions (IDP)

export const WebScopeDefinitions = {
  [WebAppScopes.OPENID]: {
    scope: "openid",
    description: "Required for OpenID Connect authentication",
    fields: ["sub"],
  },
  [WebAppScopes.PROFILE]: {
    scope: "profile",
    description: "Access to basic profile information",
    fields: [
      "name",
      "given_name",
      "family_name",
      "picture",
      "preferred_username",
      "updated_at",
    ],
  },
  [WebAppScopes.EMAIL]: {
    scope: "email",
    description: "Access to email address",
    fields: ["email", "email_verified"],
  },
  [WebAppScopes.PHONE]: {
    scope: "phone",
    description: "Access to phone number",
    fields: ["phone_number", "phone_number_verified"],
  },
};

---

M2M Scope Enum (TypeScript)

export enum EScopes {
  Onboarding = "ON_BOARDING",
  Minting = "MINTING",
  AgeVerification = "AGE_VERIFICATION",
  GeneralEvent = "GENERAL_EVENT",
  Test = "TEST",
  FileUpload = "FILE_UPLOAD",
}

---

Using M2M Scopes

Requesting Scopes During Token Acquisition

curl -X POST "https://staging-api.chainit.online/oauth/token" \
-H "Content-Type: application/json" \
-u "{clientId}:{clientSecret}" \
-d '{
  "accessTokenScopes": ["FILE_UPLOAD", "MINTING"]
}'

Verifying Scopes in Token

Decoded access token contains the granted scopes:

{
  "scope": "FILE_UPLOAD MINTING",
  "permissions": ["FILE_UPLOAD", "MINTING"],
  "azp": "<<your_client_id>>",
  "exp": 1715086400
}

---

Error Responses

Code	Description	Action
INVALID_SCOPE	Requested scope not assigned to app	Update app scopes in dev-portal
INSUFFICIENT_SCOPE	Token does not have required scope for endpoint	Request token with proper scopes

---

Best Practices

Best practices

• Least privilege: Only request scopes you need

• Validate server-side: Always verify scopes on the receiving end

• Token scopes: Granted scopes may be a subset of requested scopes

M2M Scope Usage

M2M scopes are for server-to-server API access only. They cannot be used for user authentication or login flows.