User Info

Understand the UserInfo endpoint response structure and scope-based data filtering.

UserInfo Endpoint Response

The UserInfo endpoint returns user information based on the scopes granted during authorization. The response structure varies depending on which scopes you requested and the user approved.

Base Response (Always Included)

{
  "id": "1234567890123456789",
  "user": {
    "displayName": "Duru",
    "username": "duru",
    "avatar": {
      "baseUrl": "https://pass.cengel.ai",
      "path": "/avatars/1234567890123456789/latest",
      "color": "#000"
    },
    "about": "User bio or description"
  },
  "language": "en",
  "theme": "system",
  "createdAt": "2024-01-01T00:00:00Z"
}

With email Scope

{
  "user": {
    "email": {
      "username": "john",
      "domain": "example.com",
      "isVerified": true
    }
  }
}

With details Scope

{
  "user": {
    "website": "https://example.com",
    "location": "Istanbul, Turkey",
    "birthDate": "1990-01-01"
  }
}

With phone Scope

{
  "user": {
    "phone": "+905551234567"
  }
}

With social Scope

{
  "user": {
    "socialLinks": [
      {
        "platform": "x",
        "url": "https://x.com/cengelstudio",
        "label": "X"
      },
      {
        "platform": "github",
        "url": "https://github.com/cengelstudio",
        "label": "GitHub"
      }
    ]
  }
}

With organization.read Scope

{
  "user": {
    "organization": {
      "id": "9876543210987654321",
      "name": "acme-corp",
      "role": "ADMIN",
      "domain": "acme.com"
    }
  }
}

Note: If the user is not a member of any organization, organization will be null. The role field can be "OWNER", "ADMIN", or "MEMBER".

Response Field Descriptions

Always Present Base Fields

Field	Type	Status	Description
id	string	Required	User's unique identifier (Snowflake ID as string)
user.displayName	string	Required	User's display name
user.username	string	Required	User's unique username
user.avatar.baseUrl	string	Required	Base URL for avatar images
user.avatar.path	string	Required	Path to user's avatar image
user.avatar.color	string	Required	Avatar background color (hex format)
user.about	string	May be empty	User's bio/description (may be empty string)
language	string	Required	User's preferred language code (e.g., "en", "tr")
theme	string	Nullable	User's theme preference: "light", "dark", "system", or null (system default)
createdAt	string	Required	Account creation timestamp (ISO 8601 format)

email scope Email Fields

Field	Type	Status	Description
user.email.username	string	Required	Email username part (before @)
user.email.domain	string	Required	Email domain part (after @)
user.email.isVerified	boolean	Required	Email verification status

details scope Details Fields

Field	Type	Status	Description
user.website	string	Nullable	User's website URL (null if not set)
user.location	string	Nullable	User's location string (null if not set)
user.birthDate	string	Nullable	User's birth date in YYYY-MM-DD format (null if not set)

phone scope Phone Fields

Field	Type	Status	Description
user.phone	string	Nullable	User's phone number in E.164 format (null if not set)

social scope Social Fields

Field	Type	Status	Description
user.socialLinks	array	May be empty	Array of social media link objects (empty array [] if none)
user.socialLinks[].platform	string	Required	Platform identifier (e.g., "x", "github", "linkedin")
user.socialLinks[].url	string	Required	Full URL to the social media profile
user.socialLinks[].label	string	Required	Display label for the platform

organization.read scope Organization Fields

Field	Type	Status	Description
user.organization	object	Nullable	Organization membership object (null if not in any organization)
user.organization.id	string	Required	Organization's unique identifier (Snowflake ID)
user.organization.name	string	Required	Organization's slug name
user.organization.role	string	Nullable	User's role in the organization: "OWNER", "ADMIN", or "MEMBER"
user.organization.domain	string	Required	Organization's primary domain (e.g., "acme.com")

Status Legend

Required Field is always present with a value

Nullable Field may be null if not set

May be empty Field may be empty string or empty array

Scope-Based Data Filtering

The UserInfo endpoint returns data only for scopes that the user granted during authorization. If the user didn't grant a scope, the API excludes the corresponding fields from the response.

This ensures that users have full control over what information your application can access. Check for the presence of fields before accessing them in your code.

Authentication Requirements

Include a valid access token in the Authorization header:

GET /api/v2/oauth/userinfo
Authorization: Bearer YOUR_ACCESS_TOKEN

If the token is missing or invalid, the API returns 401 Unauthorized
If the user revoked access, the API returns 403 Forbidden with "Access revoked by user"
If the user's account is banned or suspended, the API returns 403 Forbidden
The API always returns JSON, regardless of success or error

Menu