Skip to main content

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

Events Reference

Types Reference

getCurrentUser(callback)

Version added: 0.78

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

ParameterTypeDescription
callback(Result: GetCurrentUserResult) => voidA 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.

ParameterTypeDescription
callback(Result: GetCurrentUserResult) => voidA 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!

ParameterTypeDescription
callback(Result: GenerateUserSessionTokenResult) => voidA 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.

ParameterDescription
duration15 minutes from the moment of creation
payload.subUsername for the Overwolf account
payload.expToken expiry date
payload.iatToken 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": "benjo", // 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:

Example cURL request
curl -XGET -H 'Authorization: Bearer ${temp-token}' 'https://accounts.overwolf.com/tokens/short-lived/verify?extensionId=${extension-id}'
Response CodeResponse PayloadDescription
200N/AThe 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:

Example cURL request
curl -XGET -H 'Authorization: Bearer ${temp-token}' 'https://accounts.overwolf.com/tokens/short-lived/users/profile?extensionId=${extension-id}'
Response CodeResponse PayloadDescription
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

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
statusstringdeprecated. For backward compatibility only
Reasonstringdeprecated. For backward compatibility only
usernamestringunique identifier. null for not logged-in users
userIdstringsee note
machineIdstring
partnerIdint
channelstring
parametersstring
installParamsJSONsee Creating Download Link
avatarstring
installerExtensionstring
displayNamestring
uuidstringanonymous 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

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
tokenstringshort lived authentication token

LoginStateChangedEvent Object

ParameterTypeDescription
statusstring
connectionStateConnectionState enum
usernamestring
uuidstring

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

OptionDescription
Unknown
Offline
Connecting
Online
Disconnecting