Scopes Reference

Scopes determine what user data your application can access. Include them as a space-separated list in the scope parameter of your authorization request.

scope=openid+profile+email

Scope Summary

Where the Claims Arrive

Granted claims are available in two places, and both honour the same consent:

• The ID token, decoded directly from the token endpoint response. No extra call.
• The UserInfo endpoint, GET /oauth/userinfo with the access token.

sub, name, given_name, family_name, email and picture are always present in the ID token. The scope-gated claims — birthdate, phone_number, address — appear only when the matching scope was granted.

A scope your app is not allowed to hold is dropped, not rejected. Per RFC 6749 §3.3 the authorization server narrows the request to the scopes configured for your client and reports the narrowed set back in the token response. Asking for phone when your app has not been granted it produces no error — just a missing claim. Check the scope value in the token response against what you asked for, and if a scope is missing, enable it under Scopes in your app settings.

openid

Required. This scope signals that the request is an OpenID Connect authentication request. Without it, the authorization server will not return an ID token.

Claims

Example Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

When to Use

Always include openid. It is the minimum scope required for any SingleSign integration.

profile

Access to the user's basic profile information including their name, date of birth and avatar.

Claims

Example Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "middle_name": "Marie",
  "nickname": "janedoe",
  "preferred_username": "jane.doe",
  "birthdate": "1990-04-17",
  "picture": "https://api.singlesign.com/avatars/jane.jpg",
  "updated_at": 1708099200
}

When to Use

• Personalizing the UI with the user's name.
• Displaying an avatar or profile picture.
• Pre-filling form fields.
• Reading the user's date of birth at sign-up (age gating, KYC intake). SingleSign requires a date of birth at registration and enforces a minimum age of 16, so birthdate is present for anyone who signed up through the hosted flow.

Note: Not all claims may be present. If the user has not set a middle name or nickname, those fields will be absent from the response.

email

Access to the user's email address and verification status.

Claims

Example Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jane@example.com",
  "email_verified": true
}

When to Use

• Sending transactional emails (order confirmations, password resets).
• Using email as a secondary identifier or for account linking.
• Displaying the user's email in their profile.

Best practice: Always check email_verified before trusting the email address. An unverified email may not belong to the user.

phone

Access to the user's phone number and verification status.

Claims

Example Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phone_number": "+15558675309",
  "phone_number_verified": true
}

When to Use

• Sending SMS notifications.
• Contact information for support or delivery.
• Pre-filling a phone field at sign-up instead of asking for it twice.

phone_number_verified is not yet meaningful. SingleSign does not currently verify phone numbers — the number is captured at sign-up and never confirmed by OTP, and the claim is hard-coded to true. Treat phone_number as self-reported contact information. Do not use it as a possession factor for two-factor authentication or as KYC evidence until real verification exists.

The phone number is optional at sign-up. Unlike a date of birth, it is not a required registration field, so phone_number may be absent for a legitimately registered user. Handle the missing case rather than assuming it is always present.

address

Access to the user's mailing address as a structured object.

Claims

Example Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "address": {
    "formatted": "123 Main St\nAnytown, CA 90210\nUS",
    "street_address": "123 Main St",
    "locality": "Anytown",
    "region": "CA",
    "postal_code": "90210",
    "country": "US"
  }
}

When to Use

• Shipping address for e-commerce.
• Billing address for payments.
• Location-based services.

offline_access

Requests a refresh token so your application can obtain new access tokens without requiring the user to re-authenticate.

Claims

This scope does not add claims to the UserInfo response. Instead, it includes a refresh_token in the token endpoint response.

Token Response with offline_access

{
  "access_token": "eyJhbGciOiJIUzUxMiIs...",
  "id_token": "eyJhbGciOiJIUzUxMiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "openid profile email offline_access"
}

When to Use

• Background sync or data access when the user is away.
• Long-lived sessions where you don't want users to re-authenticate frequently.
• Server-side applications that need ongoing API access.

Important: Refresh tokens are sensitive credentials. Store them securely — in a server-side session, the platform keychain (mobile), or an encrypted store. Never expose them in client-side JavaScript unless absolutely necessary.

Combining Scopes

Request multiple scopes by separating them with spaces (or + in URL encoding):

scope=openid+profile+email+offline_access

The claims from all granted scopes are merged in the UserInfo response:

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "human_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane@example.com",
  "email_verified": true
}

Next Steps

• Scopes & Consent Guide — Best practices for requesting scopes.
• Tokens & Claims — How claims appear in JWTs.
• Endpoint Reference — Full API documentation.