Be a Supporter!

Browse Sections

Newgrounds Wiki: User Authentication

Newgrounds uses a session-based system to verify user sessions in our Flash API. These sessions can also be validated by approved publishers.

Acquiring the User's Session

Return to Top ^

When your game is submitted to newgrounds, 3 variables are passed along.

In a Flash game, these are passed via Flashvars, while HTML5 and iFrame games get these variables passed in a request string.

The three variables are:
  • NewgroundsAPI_SessionID - A random string that expires after 6 hours of inactivity.
  • NewgroundsAPI_UserName - The users registered name.''
  • NewgroundsAPI_UserID - The users numeric ID.''

If these variables are not set, the user is not currently signed in.

There is also a NewgroundsAPI_CustomParams variable available (see 'Custom Parameters' below).

Validating the Session

Return to Top ^

To validate the user's session, you will need a secret key. This key is used to identify that you are an approved publisher. Once you have been given a secret key, you can post the following information to our authentication script (located at

  • session_id - The session ID as set in the NewgroundsAPI_SessionID value.
  • user_name - The users name as set in the NewgroundsAPI_UserName value.''
  • secret - Your secret key.

The output of this script will be a JSON encoded object. This string will contain a 'success' variable that will be set to true or false depending on the validation results.

If the session is valid, the JSON object will also contain the user's 'user_name' and 'user_id'.

Note: For debugging purposes, you can also post to This works without actually validating your secret or the user's session id, so you can authenticate as any user while debugging. Just remember not to publish your game with this URL!

Testing Authentication

Return to Top ^

For testing purposes, we have created a user name and session id that never expire.

The user name is: API-Debugger

The session id is: D3bu64p1U53R

We have also provided a simple HTML form you can use to test the authentication output at

Custom Parameters

Return to Top ^

Some games will need to be able to direct-link users with some predefined parameters. This can be used for tracking statistics, inviting players to a specific gaming session, and so on.

These parameters can be encoded in any format (we recommend JSON), and passed via the NewgroundsAPI_CustomParams request variable.

Your encoded varaibles should be escaped (use escape() in javascript or rawurlencode() in php) to ensure they work correctly.


If your game is published at and you wanted to pass the following parameters with JSON:

  • game_id = "abcdefg"

Your JSON string would look like this: {"game_id":"abcdefg"}

You would URL encode the above JSON string and pass it to your game like using the following URL:

External URLs

Return to Top ^

For developers using our External URL option (this is an invite only option), you can customize how the session variables are passed using a double square bracket markup.

For example, you could set your External URL to this:[[NewgroundsAPI_UserName]]&user_id=[[NewgroundsAPI_UserID]]&session_id=[[NewgroundsAPI_SessionID]]

This would render the URL to something like:

If you are using custom parameters, you can also use the [[NewgroundsAPI_CustomParams]] variable.