User Info

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://id.cengel.studio",
      "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"
      }
    ]
  }
}

Response Field Descriptions

Always PresentBase 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 scopeEmail 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 scopeDetails 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 scopePhone Fields

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

social scopeSocial 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

Status Legend

RequiredField is always present with a value

NullableField may be null if not set

May be emptyField 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 returns401 Unauthorized
If the user revoked access, the API returns403 Forbiddenwith "Access revoked by user"
If the user's account is banned or suspended, the API returns403 Forbidden
The API always returns JSON, regardless of success or error

Menu