overwolf.profile API

Use this API to get Overwolf information for the current user of the app (e.g user name, user log-in event, etc.)

Permissions required: profile

Methods Reference

• overwolf.profile.getCurrentUser()
• overwolf.profile.refreshUserProfile()
• overwolf.profile.generateUserSessionToken()
• overwolf.profile.openLoginDialog()

Events Reference

• overwolf.profile.onLoginStateChanged

Types Reference

• overwolf.profile.GetCurrentUserResult Object
• overwolf.profile.GenerateUserSessionTokenResult Object
• overwolf.profile.LoginStateChangedEvent Object
• overwolf.profile.ConnectionState Enum

getCurrentUser(callback)

Version added: 0.78

Calls the given callback with the currently logged-in Overwolf user.

Parameter	Type	Description
callback	(Result: GetCurrentUserResult) => void	A function called with the current user, or an error.

refreshUserProfile(callback)

Version added: 0.128

Fetches user profile from server, then invokes the callback with the currently logged-in Overwolf user.

Parameter	Type	Description
callback	(Result: GetCurrentUserResult) => void	A function called with the current user, or an error.

generateUserSessionToken(callback)

Version added: 0.219

Generates a short lived authentication token for the currently logged-in user.

Must be logged in and connected!

This method will fail if the local user is not logged in to Overwolf!
This method will also fail if the Overwolf servers cannot be reached!

Parameter	Type	Description
callback	(Result: GenerateUserSessionTokenResult) => void	A function called with the generated token, or an error.

Generated Token note

This method generates and returns a JWT token, confirming the currently logged-in Overwolf client user.
This token can then be tested against the relevant endpoint, to confirm the authenticity of this session, for use in external applications.

Parameter	Description
duration	15 minutes from the moment of creation
payload.sub	Username for the Overwolf account
payload.exp	Token expiry date
payload.iat	Token issue date

You can view more details about the contents of a token (as well as information about JWT tokens in general) here.

Example token generation

overwolf.profile.generateUserSessionToken(console.log);

// Example result:
{
  success: true,
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvZGVkLml0a2luIiwiZXhwIjoxNjc2MzY5NjUyLCJpYXQiOjE2NzYzNjg3NTJ9.YdWqtJkFAC6-89OJ9TzU-kLHc-qWalkornFkbeEz9pg"
}

// Which also decodes to:
{
  "sub": "oded.itkin", // Username for the Overwolf account
  "exp": 1676369652, // Token expiry date
  "iat": 1676368752 // Token issue date
}

Token Expiry

The generated token expires after 15 minutes from the moment of its creation. As such, it is heavily recommended to only use this token for an initial authentication, that would then generate your own, long time token for your app's usage.

Token authentication

Verify token integrity

The token's authenticity can be verified via the following GET https request:

cURL

Example cURL request

curl -XGET -H 'Authorization: Bearer ${temp-token}' 'https://accounts.overwolf.com/tokens/short-lived/verify?extensionId=${extension-id}'

Javascript

Example Javascript request

// Loosely based on https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options
const response = await fetch(`https://accounts.overwolf.com/tokens/short-lived/verify?extensionId=${extension-id}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${temp-token}`
  },
});

Response Code	Response Payload	Description
200	N/A	The token is valid
401	{ message: "Unauthorized" }	The token is invalid

Get user profile via token

The token can be used to obtain certain details of the user's profile, via the following GET https request:

cURL

Example cURL request

curl -XGET -H 'Authorization: Bearer ${temp-token}' 'https://accounts.overwolf.com/tokens/short-lived/users/profile?extensionId=${extension-id}'

Javascript

Example Javascript request

// Loosely based on https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options
const response = await fetch(`https://accounts.overwolf.com/tokens/short-lived/users/profile?extensionId=${extension-id}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${temp-token}`
  },
});

Response Code	Response Payload	Description
200	{ avatar: ImageURL nickname: string username: string }	The profile of the user associated with the token
401	{ message: "Unauthorized" }	Something went wrong

openLoginDialog()

Version added: 0.80

Opens the login dialog.

onLoginStateChanged

Version added: 0.78

Fired when a user logged in or logged out, with the following structure: LoginStateChangedEvent Object

GetCurrentUserResult Object

Parameter	Type	Description
success	boolean	inherited from the "Result" Object
error	string	inherited from the "Result" Object
status	string	deprecated. For backward compatibility only
Reason	string	deprecated. For backward compatibility only
username	string	unique identifier. null for not logged-in users
userId	string	see note
machineId	string
partnerId	int
channel	string
parameters	string
installParams	JSON	see Creating Download Link
avatar	string
installerExtension	string
displayName	string
uuid	string	anonymous unique user id. null for not logged-in users

Note: userId is not a unique identifier

The term userId might be a bit misleading: it's not a unique identifier for an Overwolf user. The userId is unique for each OW client installation on the current machine, so it's more like "clientID".
We use it to identify not logged-in users on the machine.

On a Windows computer, with multiple users - there might be multiple userIds but a single MachineId;

To uniquely identify logged-in users, you should use the username (this field will be null for not logged-in user).

Each user has to pick a unique OW username upon registering. Even If he logged in through Google, Discord, etc. - OW automatically generate a unique user name for him.
So at the bottom line, you can always count on the username to be a unique identifier for logged-in users.

Example data: Success

{
   "success": true,
   "error": "",
   "username":"itaygl",
   "userId":"OW_34153336-192b-44f6-aa0f-4a9b744c689d",
   "machineId":"653000ad-001c-43e9-a5c9-e23db5ad370a",
   "partnerId":0,
   "channel":"website",
   "displayName": "itay gl", 
   "avatar": "https://lh5.googleusercontent.com/-vvsdlz7W2oM/AAAAAAAAAAI/AAAAAAAAAAA/ACHi3reB9VADjY3FzaTDSA7-Adrsny38xg/mo/photo.jpg?sz=50",
   "installParams":  "{source: "", medium: "", campaign: "", term: "", content: """,
}

Example data: Failure

If the user is not logged-in, the success will be false, but you’ll still get the rest of the available data (userId, machineId, etc.)

{  
   "success": false,
   "error": "Not signed in",
   "status":"error",
    "reason":"Not signed in",
   "username":null,
   "userId":"OW_34153336-192b-44f6-aa0f-4a9b744c689d",
   "machineId":"653000ad-001c-43e9-a5c9-e23db5ad370a",
   "partnerId":0,
   "channel":"website",
   "parameters":{"no-ftue":null},
   "installParams":null,
   "avatar":""
}

GenerateUserSessionTokenResult Object

Parameter	Type	Description
success	boolean	inherited from the "Result" Object
error	string	inherited from the "Result" Object
token	string	short lived authentication token

LoginStateChangedEvent Object

Parameter	Type	Description
status	string
connectionState	ConnectionState enum
username	string
uuid	string

Event data example: Success

{
    "status": "success",
    "connectionState": "Online",  // can be "Online", "Offline", "Connecting", etc.
    "username": "..."   // when the status is other than "Offline", will be the currently connected username.
}

ConnectionState enum

Option	Description
Unknown
Offline
Connecting
Online
Disconnecting