Web API Spec - SWG-Source/swg-main GitHub Wiki

To implement authentication and other features, you will need to provide some API endpoints in your web application. Here are some examples of the kinds of requests and responses you'll need to handle.

Authenticate a user

The following server configuration values are required to use authentication. The URL should be set to the appropriate API endpoint for your application.

[LoginServer]
useExternalAuth=true
externalAuthURL=http://example.com/api/auth

Optionally, you can specify how the request will be made. JsonWebApi is recommended. You can also set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended.

useJsonWebApi=true
externalAuthSecretKey=somesuperdupersecretkey

If you have JsonWebApi enabled, whenever someone tries to log into SWG, the server will send a POST request to your AuthURL that looks like this:

### Request
Content-Type: application/json

{
  "user_name": "playsswgyodadoes",
  "user_password": "securethisis",
  "stationID": "123456",
  "ip": "123.456.789.012",
  "secretKey": "somesuperdupersecretkey"
}

When your web application receives this request, you can authenticate the request with the secret key and then check the username and password against your users table. If you have systems for banning players, etc, this would be the time to check for that kind of stuff as well. If you want to log the IP and the Station ID of the user, you can do that too. Then, your application should send the response in JSON format. If you want to let the player in, message should be set to success.

### Response
Content-Type: application/json

{
  "message": "success"
}

Otherwise, you can set message to anything you like and this will be displayed to the user as an error message in the swg client.

### Response
Content-Type: application/json

{
  "message": "Account does not exist or password was incorrect"
}

For the sake of completeness, if useJsonWebApi is set to false, The same values are passed as POST variables instead. This only affects the request. You should still form your response as JSON in the same way.

Admin Levels

You can have your SWG server fetch a user's admin level from your web application as an alternative to using an admin account datatable. (The admin level is typically a number between 0 and 50 to control how much access a user has to god mode on a server. 0 is none, 50 is everything. The specific capabilities for each admin level is beyond the scope of this document.)

To do this, you need to set the following server configuration. The URL should be set to the appropriate API endpoint for your application.

[ServerUtility]
externalAdminLevelsEnabled=true
externalAdminLevelsURL=http://example.com/api/adminlevel

Optionally, you can set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended.

externalAdminLevelsSecretKey=somesuperdupersecretkey

Now, when a player tries to /setgod, the server will send a POST request to your API. The username and (optionally) the secret key will be sent as POST variables.

### Request
Content-Type: application/x-www-form-urlencoded

user_name=playsswgyodadoes&secretKey=somesuperdupersecretkey

You can then get the admin level for this user from your application and send it back in JSON format like this:

### Response
Content-Type: application/json

{
  "message": 50
}

Server Metrics

NOTE: The following is a very brief overview. For many more details about using these server metrics, see this wiki page.

You can configure your SWG server to periodically send some statistics about your server to your web application. This is useful for indicating whether your server is online and how many players are logged in.

To do this, you'll need to set a few server configuration values. The URL should be the appropriate API endpoint for your application. The interval sets how often the server should send stats.

[CentralServer]
metricsDataURL=http://example.com/api/metrics
webUpdateIntervalSeconds=5

Optionally, you can set a secret key that will be sent with each request so that you can confirm that the request is actually coming from your server. Using HTTPS is reccomended.

metricsSecretKey=somesuperdupersecretkey

Now, the server will send a JSON object at the set interval:

### Request
Content-Type: application/json

{
  "clusterName": "yourCluster",
  "totalPlayerCount": 50,
  "totalGameServers": 1,
  "totalPlanetServers": 1,
  "totalTutorialSceneCount": 1,
  "lastLoadingStateTime": 456456,
  "clusterStartupTime": 600,
  "timeClusterWentIntoLoadingState": 0,
  "webUpdateIntervalSeconds": 5,
  "secretKey": "somesuperdupersecretkey"
}

You'll have to implement some of your own logic to infer the server's status:

The server is offline if the last metrics update was recieved longer ago than webUpdateIntervalSeconds
The server is loading if lastLoadingStateTime == 0
The server is online if timeClusterWentIntoLoadingState == 0