Getting Started

mod.io API v1

Welcome to the official documentation for mod.io, an API for developers to add mod support to their games. Using our SDKs and plugins for popular and custom game engines, getting your creator community started and making the mods they create discoverable and installable via your in-game menu is straight forward, with full cross-platform support. If you are a game developer, you can manage your games and API access via your mod.io library dashboard. If you are a user creating tools and apps, you can request API access via your mod.io account.

API path: https://*.modapi.io/v1 (see your API access dashboard)

Current version: v1 (latest)

View Version Changelog

How It Works

Compatible with all builds of your game on all platforms and stores, mod.io is a clientless and standalone solution which gives you complete control over your modding ecosystem.

Implementation

Once you have added your game to mod.io and got your game ID and API key, you can start integrating the mod.io REST API into your game, tools and sites. There are 3 options to get connected which you can use interchangeably depending on your needs. Here's the breakdown of each option.

Official Tools

Plugins and wrappers made or supported by the mod.io team

	-	-	-
	Unity Plugin SDK Getting Started Sample Project		Unreal Plugin SDK Getting Started UE4 Sample Project UE5 Sample Project
	GameMaker SDK Getting Started		C/C++ SDK SDK Getting Started
	Discord Bot Instructions Invite

Community Tools

Plugins and wrappers made by our awesome community. Is there a tool out there that should be added to the list? Get in touch!

	-	-	-
	Construct 2 Plugin SDK Getting Started		Haxe Wrapper SDK Getting Started
	Modio.NET SDK Getting Started		Rust Wrapper SDK Getting Started Tutorials
	Python Wrapper SDK Getting Started Tutorials		Common Lisp Github Getting Started
	Command Line Tool CMD Getting Started		GitHub Action Mod Uploader GitHub Usage

Here is a brief list of the things to know about our API, as explained in more detail in the following sections.

• All requests to the API must be made over HTTPS (TLS).
• All API responses are in application/json format.
• Any POST request with a binary payload must supply the Content-Type: multipart/form-data header.
• Any non-binary POST, PUT and DELETE requests must supply the Content-Type: application/x-www-form-urlencoded header.
• Any non-binary payload can be supplied in JSON format using the input_json parameter.

Authentication

Authentication can be done via 5 ways:

• Use an API key for Read-only access (get a test environment API key here)
• Use the Email Authentication Flow for Read and Write access (it creates an OAuth 2 Access Token via email)
• Use the Platform Authentication Flow for Read and Write access (it creates an OAuth 2 Access Token automatically on popular platforms such as Steam and Xbox)
• Use the OpenID Authentication Flow for Read and Write access (it creates an OAuth 2 Access Token automatically using your identity provider for SSO)
• Manually create an OAuth 2 Access Token for Read and Write access (get a test environment OAuth 2 token here)

All users and games are issued an API key which must be included when querying the API. It is quick and easy to use but limited to read-only GET requests, due to the limited security it offers. If you want players to be able to add, edit, rate and subscribe to content, you will need to use an authentication method that generates an OAuth 2 Access token. These authentication methods are explained in detail here.

You can use an OAuth 2.0 bearer token instead of an API key for GET endpoints (excluding Authentication endpoints). But remember, if you provide both an Access Token (OAuth 2) and an API key in one request, the access token takes precedence and the API key is ignored. So, always ensure you use a valid access token and have the process in place to get a new token when the old one expires.

Web Overlay Authentication

At the moment it is not possible to open the mod.io website in-game with the user pre-authenticated, however you can provide a hint by appending ?portal=PORTAL to the end of the URL. What this tells mod.io, is that when the user attempts to perform an action that requires authentication, they will be prompted to login with their PORTAL account. For example if you want to take a mod creator to their mod webpage in-game on Steam, the URL would look something like: https://mod.io/g/gamename/m/modname?portal=steam. You can optionally add &login=auto as well to automatically start the login process. Supported portals can be found here.

Scopes (OAuth 2)

mod.io allows you to specify the permission each access token has (default is read+write), this is done by the use of scopes. See below for a full list of scopes available, you must include at least one scope when generating a new token.

Making Requests

Requests to the mod.io API are to be over HTTPS (Port 443), any requests made over HTTP will return a 400 Bad Request response.

Using an API Key

curl -X get https://*.modapi.io/v1/games?api_key=xxxxxxxxxxxxxxxx

To authenticate using your unique 32-character API key, append the api_key=xxxxxxxxxxxxxxxx parameter to the end of your request. Remember that using an API key means requests are read-only, if you want to create, update or delete resources - authentication via OAuth 2 is required which you can set up with your api key.

Using an Access Token

Example POST request with no binary files

curl -X POST https://*.modapi.io/v1/games/1/mods/1/tags \
  -H 'Authorization: Bearer your-token-here' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'tags[]=Unity' \
  -d 'tags[]=FPS'

To authenticate using an OAuth 2 access token, you must include the HTTP header Authorization in your request with the value Bearer your-token-here. Verification via Access Token allows much greater power including creating, updating and deleting resources that you have access to. Also because OAuth 2 access tokens are tied to a user account, you can personalize the output by viewing content they are subscribed and connected to via the me endpoint and by using relevant filters.

Access Token Lifetime & Expiry

By default, all access token's are long-lived - meaning they are valid for a common year (not leap year) from the date of issue. You should architect your application to smoothly handle the event in which a token expires or is revoked by the user themselves or a mod.io admin, triggering a 401 Unauthorized API response.

If you would like tokens issued through your game to have a shorter lifespan, you can do this by providing the date_expires parameter on any endpoint that returns an access token such as the Email Exchange or Authenticate via Steam endpoints. If the parameter is not supplied, it will default to 1 year from the request date, if the supplied parameter value is above one year or below the current server time it will be ignored and the default value restored.

Request Content-Type

If you are making a request that includes a file, your request Content-Type header must be multipart/form-data, otherwise if the request contains data (but no files) it should be application/x-www-form-urlencoded, which is UTF-8 encoded.

Example POST request with binary file

curl -X POST https://*.modapi.io/v1/games/1/mods \
  -H 'Authorization: Bearer your-token-here' \
  -H 'Content-Type: multipart/form-data' \ 
  -F 'logo=@path/to/image.jpg' \
  -F 'name=Rogue Knight Clear Skies' \
  -F 'homepage=http://www.clearsies-rk.com/' \
  -F 'summary=It rains in Rogue Knight an awful lot, want sunshine all the time? Yeah you do.'

If the endpoint you are making a request to expects a file it will expect the correct Content-Type as mentioned. Supplying an incorrect Content-Type header will return a 415 Unsupported Media Type response.

JSON Request Data

Example json-encoded POST request

curl -X POST https://*.modapi.io/v1/games/1/mods/1/team \
  -H 'Authorization: Bearer your-token-here' \
  -H 'Content-Type: application/x-www-form-urlencoded' \  
  -d 'input_json={
        "email": "developers@mod.io",
        "level": 8,
        "position": "King in the North"
      }'

For POST & PUT requests that do not submit files you have the option to supply your data as HTTP POST parameters, or as a UTF-8 encoded JSON object inside the parameter input_json which contains all payload data. Regardless, whether you use JSON or not the Content-Type of your request still needs to be application/x-www-form-urlencoded with the data provided in the body of the request.

NOTE: If you supply identical key-value pairs as a request parameter and also as a parameter in your JSON object, the JSON object will take priority.

Response Content-Type

Responses will always be returned in application/json format.

Response Codes

Here is a list of the most common HTTP response codes you will see while using the API.

Errors

Error object

"error": {
    "code": 403,
    "error_ref": 15024,
    "message": "You do not have the required permissions to access this resource."
}

If an error occurs, mod.io returns an error object with the HTTP code, error_ref and message to describe what happened and when possible how to avoid repeating the error. It's important to know that if you encounter errors that are not server errors (500+ codes) - you should review the error message before continuing to send requests to the endpoint.

When requests contain invalid input data or query parameters (for filtering), an optional field object called errors can be supplied inside the error object, which contains a list of the invalid inputs. The nested errors object is only supplied with 422 Unprocessable Entity responses. Be sure to review the Response Codes to be aware of the HTTP codes that the mod.io API returns.

Error object with input errors

"error": {
    "code": 422,
    "error_ref": 13009,
    "message": "Validation Failed. Please see below to fix invalid input.",
    "errors": {
        "summary":"The mod summary cannot be more than 200 characters long.",
    }
}

Remember that Rate Limiting applies whether an error is returned or not, so to avoid exceeding your daily quota be sure to always investigate error messages - instead of continually retrying.

Error Codes

Along with generic HTTP response codes, we also provide mod.io specific error codes to help you better understand what has gone wrong with a request. Below is a list of the most common error_ref codes you could encounter when consuming the API, as well as the reason for the error occuring. For error codes specific to each endpoint, click the 'Show All Responses' dropdown on the specified endpoint documentation.

Example request with malformed api_key

curl -X GET https://*.modapi.io/v1/games?api_key=malformed_key

{
    "error": {
        "code": 401,
        "error_ref": 11001,
        "message": "We cannot complete your request due to a malformed/missing api_key in your request. Refer to documentation at https://docs.mod.io"
    }
}

Response Formats

Single object response

{
    "id": 2,
    "mod_id": 2,
    "date_added": 1499841487,
    "date_scanned": 1499841487,
    "virus_status": 0,
    "virus_positive": 0,
    "virustotal_hash": "f9a7bf4a95ce20787337b685a79677cae2281b83c63ab0a25f091407741692af-1508147401",
    "filesize": 15181,
    "filehash": {
      "md5": "2d4a0e2d7273db6b0a94b0740a88ad0d"
    },
    "filename": "rogue-knight-v1.zip",
    "version": "1.3",
    "changelog": "VERSION 1.3 -- Changes -- Fixed critical castle floor bug.",
    "metadata_blob": "rogue,hd,high-res,4k,hd-textures",
    "download": {
      "binary_url": "https://*.modapi.io/v1/games/1/mods/1/files/1/download",
      "date_expires": 1579316848
    }
}

The way in which mod.io formats responses is entirely dependant on whether the requesting endpoint is returning a single item or a collection of items.

Single item Responses

For single items, mod.io returns a single JSON object which contains the requested resource. There is no nesting for single responses.

Multiple item Responses

Endpoints that return more than one result, return a JSON object which contains a data array and metadata fields:

• data - contains all data returned from the request.
• metadata fields - contains pagination metadata to help you paginate through the API.

Multiple objects response

{
    "data": [
        {
            "id": 2,
            "mod_id": 2,
            "date_added": 1499841487,
            "date_scanned": 1499841487,
            "virus_status": 0,
            "virus_positive": 0,
            "virustotal_hash": "f9a7bf4a95ce20787337b685a79677cae2281b83c63ab0a25f091407741692af-1508147401",
            "filesize": 15181,
            "filehash": {
              "md5": "2d4a0e2d7273db6b0a94b0740a88ad0d"
            },
            "filename": "rogue-knight-v1.zip",
            "version": "1.3",
            "changelog": "VERSION 1.3 -- Changes -- Fixed critical castle floor bug.",
            "metadata_blob": "rogue,hd,high-res,4k,hd-textures",
            "download": {
              "binary_url": "https://*.modapi.io/v1/games/1/mods/1/files/1/download/c489a0354111a4d76640d47f0cdcb294",
              "date_expires": 1579316848
            }
        },
        {
            ...
        },
    ],
    "result_count": 100,
    "result_limit": 100,
    "result_offset": 0,
    "result_total": 127
}  

Status & Visibility

To manage games and mods via the API we use the fields status and visible. The values of these fields determines what is returned in API requests, so it is important to understand who is authorized to view what content.

Visible attribute states & privileges

Only mods use the visible attribute allowing mod admins to control their availability. Public is the default value:

Status attribute states & privileges

Games and mods use the status attribute allowing game admins to control their availability. For mods this is important because it allows game admins to control which mods are available without changing the visible value set by the mod admin. Not accepted is the default value until changed by a game admin, or if a file is added to a mods profile it will be moved to an accepted state (provided the game developer has elected "not to curate" new mods):

Game admin privileges

As a game admin, you can modify your games status to show or hide it from API requests. When a game is not accepted you can still view it provided you are the games admin or using the games api_key. You can call Get User Games endpoint to retrieve all games associated with the authenticated user regardless of their status.

By default mods connected to a game will not be returned if they are hidden or not accepted. As a game admin, you can modify a mods status and visible fields and filter by these values (to view content normal users cannot see). We recommend you only change the status and let mod admins control the visible field.

Mod admin privileges

As a mod admin, you can modify visible to show or hide your mod from API requests. You cannot modify the status of your mod. When a mod is hidden you can still view it provided you are the mods admin or subscribed to the mod. You can call Get User Mods endpoint to retrieve all mods associated with the authenticated user regardless of their status and visible.

Valid status & visibility filters

status=1
status-in=0,1
visible=1 
visible-in=0,1

Game Admin Only status & visibility filters

status-not-in=1,2
status-gt=1
visible-not-in=1
visible-st=1

Important Note When Filtering

Due to the requirement of certain status & visible values only being available to administrators. We have restricted the amount of filters available for non-game admins and thus for both of these fields only direct matches = and -in are permitted. Attempting to apply game admin filters without the required permissions will result in a 403 Forbidden error response.

Pagination

When requesting data from endpoints that contain more than one object, you can supply an _offset and _limit to paginate through the results. Think of it as a page 1, 2, 3... system but you control the number of results per page, and the page to start from. Appended to each response will be the pagination metadata:

Metadata example

"result_count": 100,
"result_limit": 100,
"result_offset": 0,
"result_total": 127

_limit (Limit)

v1/games?_limit=5

Limit the number of results for a request. By default 100 results are returned per request:

• ?_limit=5 - Limit the request to 5 individual results.

_offset (Offset)

v1/games?_offset=30

Use _offset to skip over the specified number of results, regardless of the data they contain. This works the same way offset does in a SQL query:

• ?_offset=30 - Will retrieve 100 results after ignoring the first 30 (31 - 130).

Combining offset with a limit

v1/games?_offset=30&_limit=5

You can combine offset with a limit to build queries that return exactly the number of results you want:

• ?_offset=30&_limit=5 - Will retrieve 5 results after ignoring the first 30 (31 - 35).

If the result_count parameter matches the result_limit parameter (5 in this case) in the response, that means there are probably more results to get, so our next query might be:

• ?_offset=35&_limit=5 - Will retrieve the next 5 results after ignoring the first 35 (36 - 40).

Sorting

All endpoints are sorted by the id column in ascending order by default (oldest first). You can override this by including a _sort with the column you want to sort by in the request. You can sort on all columns in the parent object only. You cannot sort on columns in nested objects, so if a game contains a tags object you cannot sort on the tag name column, but you can sort by the games name since the games name resides in the parent object.

NOTE: Some endpoints like Get Mods have special sort columns like popular, downloads, rating and subscribers which are documented alongside the filters.

_sort (Sort)

v1/games?_sort=name

Sort by a column, in ascending or descending order.

• ?_sort=name - Sort name in ascending order

• ?_sort=-name - Sort name in descending order (by prepending a -)

Filtering

mod.io has powerful filtering available to assist you when making requests to the API. You can filter on all columns in the parent object only. You cannot apply filters to columns in nested objects, so if a game contains a tags object you cannot filter by the tag name column, but you can filter by the games name since the games name resides in the parent object.

_q (Full text search)

v1/games?_q=The Lord Of The Rings

Full-text search is a lenient search filter that is only available if the endpoint you are querying contains a name column. Wildcards should not be applied to this filter as they are ignored.

• ?_q=The Lord of the Rings - This will return every result where the name column contains any of the following words: 'The', 'Lord', 'of', 'the', 'Rings'.

= (Equals)

v1/games?id=10

The simplest filter you can apply is columnname equals. This will return all rows which contain a column matching the value provided.

• ?id=10 - Get all results where the id column value is 10.

-not (Not Equal To)

v1/games?curation-not=1

Where the preceding column value does not equal the value specified.

• ?curation-not=1 - Where the curation column does not equal 1.

-lk (Like + Wildcards)

v1/games?name-lk=texture

v1/games?name-lk=texture*

v1/games?name-lk=*texture*

Where the string supplied matches the preceding column value. This is equivalent to SQL's LIKE. Wildcard's * can be used to find content that partially matches as described below.

• ?name-lk=texture - Get all results where the name column value is 'texture'.
• ?name-lk=texture* - Get all results where the name column value begins with 'texture'. This means the query would return results for 'texture', 'textures' and 'texture pack'
• ?name-lk=*texture* - Get all results where the name column value contains 'texture'. This means the query would return results for 'texture', 'HD textures' and 'armor texture pack'

-not-lk (Not Like + Wildcards)

v1/games?name-not-lk=dungeon

Where the string supplied does not match the preceding column value. This is equivalent to SQL's NOT LIKE. Wildcard's * can be used as described above.

• ?name-not-lk=dungeon - Get all results where the name column value is not 'dungeon'.

-in (In)

v1/games?id-in=3,11,16,29

Where the supplied list of values appears in the preceding column value. This is equivalent to SQL's IN.

• ?id-in=3,11,16,29 - Get all results where the id column value is 3, 11, 16 and 29.

-not-in (Not In)

v1/games?modfile-not-in=8,13,22

Where the supplied list of values does not equal the preceding column value. This is equivalent to SQL's NOT IN

• ?modfile-not-in=8,13,22 - Get all results where id column does not equal 8, 13 and 22.

-max (Smaller Than or Equal To)

v1/games?game-max=40

Where the preceding column value is smaller than or equal to the value specified.

• ?game-max=40 - Get all results where the game smaller than or equal to 40.
  

-min (Greater Than or Equal To)

v1/games?game-min=20

Where the preceding column value is greater than or equal to the value specified.

• ?game-min=20 - Get all results where the game column is greater than or equal to 20.

-bitwise-and (Bitwise AND)

v1/games?maturity_option-bitwise-and=5

Some columns are stored as bits within an integer. Their value depends on the bits selected. For example, suppose a column has 4 options:

• 1 = Option A
• 2 = Option B
• 4 = Option C
• 8 = Option D

You can combine any of these options by adding them together which means there are (2 ^ 4 = 16 possible combinations). For example Option A (1) and Option C (4) would be (1 + 4 = 5), Option A (1), Option C (4) and Option D (8) would be (1 + 4 + 8 = 13), all Options together would be (1 + 2 + 4 + 8 = 15).

The number of combinations makes using equals, in and other filters a little complex. To solve this we support Bitwise AND (&) which makes it easy to match a column which contains any of the options you want.

• ?maturity_option-bitwise-and=5 - Will match the maturity_option column values 1, 3, 4, 5, 6, 7, 9, 11, 12, 13, 14, 15 (since these values contain the bits 1, 4 or both).

Localization

Localized Responses

Example HTTP Header Request
---------------------
HTTP/2.0 200 OK
...
...
Accept-Language: de

Example response (assuming a validation error occurred)

{
    "error": {
        "code": 422,
        "message": "Überprüfung fehlgeschlagen. Bitte lesen Sie unten, um ungültige Eingaben zu korrigieren:",
        "errors": {
            "name": "Name darf maximal 50 Zeichen haben."
        }
    }
}

The mod.io API provides localization for a collection of languages. To specify responses from the API to be in a particular language, simply provide the Accept-Language header with an ISO 639 compliant language code. If a valid language code is not provided and the user is authenticated, the language they have selected in their profile will be used. All other requests will default to English (US). The list of supported codes includes:

Example request updating specified fields with Polish translations.

curl -X POST https://*.modapi.io/v1/games/1/mods/1 \
    -H 'Authorization: Bearer your-token-here' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Content-Language: pl' \
    -d 'name=Zaawansowany rozkwit Wiedźmina' \
    -d 'summary=Zobacz zaawansowany mod oświetlenia w Kaer Morhen w zupełnie nowym świetle' 

Attempt to retrieve Polish translations within supported fields.

curl -X GET https://*.modapi.io/v1/games/1/mods/1 \
    -H 'Authorization: Bearer your-token-here' \
    -H 'Accept-Language: pl'

NOTE: Localization for mod.io is currently a work-in-progress and thus not all responses may be in the desired language.

Response

{
    "id": 1,
    "game_id": 1,
    ...
    "name": "Zaawansowany rozkwit Wiedźmina", 
    "summary": "Zobacz zaawansowany mod oświetlenia w Kaer Morhen w zupełnie nowym świetle"
}

Localized Requests

Specific endpoints also allow you to submit fields in the supported languages above. To tell the API you are submitting non-english content you must supply the Content-Language header in the request with a valid language code (see above). When you supply the Content-Language header in your request, you are explicitly indicating to the API that all eligible fields have been translated into the supplied language and if a user (or client) requests the respective language, the value for that supplied field will be returned.

A brief summary when dealing with localized requests and responses:

• English is still required as the default value when creating and updating a resource.
• If you don't supply a valid Content-Language header value, all input data will be assumed English.
• If you don't supply a valid Accept-Language header value, all response data will be in English.
• If you supply a valid Accept-Language header value, all response data will be in English unless translations exist in the requested language.
• Only fields that contain the localization icon in the parameter section of the endpoint can be submitted in different languages.

Rate Limiting

mod.io implements rate limiting to stop users abusing the service. Exceeding the rate limit will result in requests receiving a 429 Too Many Requests response until the reset time is reached.

It is highly recommended you architect your app to check for the 429 Too Many Requests HTTP response code, and ensure you do not continue to make requests until the duration specified in the retry-after header (in seconds) passes. Be aware we enforce global rate limits which will result in all requests being blocked (error ref 11008). We also enforce per-endpoint rate limits which will only result in requests to that endpoint being blocked (error ref 11009) until the duration specified in the retry-after header (in seconds) passes, allowing you to continue to call other endpoints. Users who continue to send requests despite a 429 response could potentially have their credentials revoked. The following limits are implemented by default:

Global API key Rate Limiting

• API keys linked to a game have unlimited requests.
• API keys linked to a user have 60 requests per minute.

Global OAuth2 Rate Limiting

• User tokens are limited to 120 requests per minute.
• User token writes are limited to 60 requests per minute.

Global IP Rate Limiting

• IPs are limited to 1000 requests per minute.
• IP writes are limited to 60 requests per minute.

Per-Endpoint Rate Limiting

• Certain endpoints may override the defaults for security, spam or other reasons.
• When this (error ref 11009) is encountered, its ok to continue requesting other endpoints, as the retry-after only applies to this endpoint.

Headers

Example HTTP Header Response
---------------------
HTTP/2.0 429 Too Many Requests
...
...
retry-after: 57

Example ratelimit JSON response

{
    "error": {
        "code": 429,
        "error_ref": 11008,
        "message": "You have made too many requests in a short period of time, please wait and try again soon."
    }
}

If the rate limit is exceeded, the following header will be returned alongside the 429 Too Many Requests HTTP response code.

• retry-after - Number of seconds before you can attempt to make another request to API. NOTE: If the retry-after value is 0, that means you have hit a rolling ratelimit. Rolling ratelimits don't block for a set timeframe once the limit is reached, instead they permit a certain number of requests within the timeframe (see this explanation). If you encounter a 0, we recommend retrying the endpoint again after 60 seconds.

Deprecation Notice

From November 20th, 2022 - the rate limit headers below will no longer be returned. If you have written a custom mod.io SDK or library, you should replace any usage of these headers with retry-after.

• X-RateLimit-Limit - Number of requests you can make from the supplied API key/access token per minute.
• X-RateLimit-Remaining - Number of requests remaining until requests are rejected.
• X-RateLimit-RetryAfter - Amount of seconds until reset once you have been throttled (Only returned once rate limit exceeded).

From January 1st, 2024 - the error ref 11009 will be returned when a rate limit applies only to the endpoint being called. Error ref 11008 will continue to be returned in all other scenarios where the rate limit applies to all endpoints.

Optimize your requests

You should always plan to minimize requests and cache API responses. It will make your app feel fluid and fast for your users. If your usage is excessive we shall reach out to discuss ways of optimizing, but our aim is to never restrict legitimate use of the API. We have set high limits that should cover 99% of use-cases, and are happy to discuss your scenario if you require more.

Testing

To help familiarize yourself with the mod.io API and to ensure your implementation is battle-hardened and operating as intended, we have setup a test sandbox which is identical to the production environment. The test sandbox allows you to make requests to the API whilst your integration is a work in progress and the submitted data is not important. When you are ready to go live it's as easy as adding your game to the production environment, substituting the test API path for the production API path, and updating the api_key and game_id you are using to the values from your games profile on production.

To begin using the test sandbox you will need to register a test account and add your game. You will only see games you are a team member of and there is no connection between the data added to the test environment and production. We highly recommend you use the test environment when integrating as it allows you to keep your development private, and you can submit as much dummy data as you need to try the functionality required, without having to clean it up at the end.

Test version: v1

Test site: https://test.mod.io

Test API path: https://api.test.mod.io/v1

NOTE: We periodically reset the test environment to default - with the exception of user accounts so please do not rely on it to store important information. Any data you intend on persisting should be submitted to the production environment.

Whitelabel

If you are a large studio or publisher and require a private, in-house, custom solution that accelerates your time to market with a best-in-class product, reach out to developers@mod.io to discuss the licensing options available.

Contact

If you spot any errors within the mod.io documentation, have feedback on how we can make it easier to follow or simply want to discuss how awesome mods are, feel free to reach out to developers@mod.io or come join us in our discord channel. We are here to help you grow and maximise the potential of mods in your game.

Platforms

Targeting a Platform

mod.io supports mods on all platforms. Games can enable per-platform mod file support in their dashboard, if they wish to control which platforms each mod and their corresponding files can be accessed on. Otherwise, all mods and their files will be available on all platforms the game supports. To make this system work, it's important the following headers are included in all API requests as explained below. If you have any questions about setting up cross-platform mod support in your game, please reach out to developers@mod.io.

When making API requests you should include the X-Modio-Platform header (with one of the values below), to tell mod.io what Platform the request is originating from. This header is important because it enables mod.io to return data that is approved for the platform such as:

• Supported mods and files
• Supported tags the player can filter on
• Localization of content for the platform
• It also enables platform specific metrics

For example, passing the HTTP header X-Modio-Platform: xboxseriesx in your API request tells mod.io your player is on Xbox Series X.

Official mod.io Plugins and SDKs will automatically supply this value for you providing you have specified the correct platform in the tools' settings. We strongly recommend you supply this header in every request with the correct platform to enable mod.io to provide the best cross-platform experience for your players. Please see a list of supported platforms below:

These are the only supported values and are case-insensitive, anything else will be ignored and default to windows. Have we missed a platform you are using? Get in touch!

Targeting a Portal

When making API requests you should include the X-Modio-Portal header (with one of the values below), to tell mod.io what Portal (eg. Store or App) the request is originating from. This header is important because it enables mod.io to fine-tune the experience, such as returning display names used by players on that portal (which can be a certification requirement).

For example, passing the HTTP header X-Modio-Portal: epicgames in your API request tells mod.io your player is coming via the Epic Games Store.

You can also instruct the mod.io website to authenticate the player using a portal from the list above (provided it is supported), as explained in Web Overlay Authentication. For example, if your game client has logged the player into mod.io on PlayStation using their PlayStation™Network account, and you want to open the mod.io website in-game with the player logged in using the same authentication method, you would add ?portal=psn to the end of the URL: https://mod.io/g/gamename?portal=psn. You can optionally add &login=auto as well to automatically start the login process.

These are the only supported values and are case-insensitive, anything else will be ignored. Have we missed a portal you are using? Get in touch!

Authentication

Terms

Example request

# You can also use wget
curl -X GET https://*.modapi.io/v1/authenticate/terms?api_key=YourApiKey \
  -H 'Accept: application/json'

GET https://*.modapi.io/v1/authenticate/terms?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io

Accept: application/json

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/authenticate/terms',
  method: 'get',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/authenticate/terms?api_key=YourApiKey',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://*.modapi.io/v1/authenticate/terms', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/authenticate/terms?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /authenticate/terms

The purpose of this endpoint is to provide the text, links and buttons you can use to get a users agreement and consent prior to authenticating them in-game (your dialog should look similar to the example below). This text will be localized based on the Accept-Language header, into one of our supported languages (note: our full Terms of Use and Privacy Policy are currently in English-only). If you are authenticating using platform SSO, you must call this endpoint with the X-Modio-Portal header set, so the text is localized to match the platforms requirements. A successful response will return a Terms Object.

Example Dialog:

IMPORTANT: It is a requirement of the Game Terms with mod.io, and the platforms mod.io is used on, to ensure the user provides consent and has agreed to the latest mod.io Terms of Use and Privacy Policy. The users agreement must be collected prior to using a 3rd party authentication flow (including but not limited to Steam, PSN, Nintendo and Xbox Live). You only need to collect the users agreement once, and also each time these policies are updated.

To make this easy to manage, all of the 3rd party authentication flows have a terms_agreed field which should be set to false by default. If the user has agreed to the latest policies, their authentication will proceed as normal, however if their agreement is required and terms_agreed is set to false an error 403 Forbidden (error_ref 11074) will be returned. When you receive this error, you must collect the users agreement before resubmitting the authentication flow with terms_agreed set to true, which will be recorded.

NOTE: You must make sure the Terms of Use and Privacy Policy are correctly linked, or displayed inline using the agreements endpoints to get the latest versions.

If you wish to display the agreements in a web browser overlay, we recommend adding /widget and ?no_links=true to the end of the agreement URLs, to remove the menus and external links, for example:

- https://mod.io/terms/widget?no_links=true
- https://mod.io/privacy/widget?no_links=true

NOTE: You can use your own text and process, but be aware that you are responsible for ensuring that the users agreement is properly collected and reported. Failure to do so correctly is a breach of the mod.io Game Terms. If your game does not authenticate users or only uses the email authentication flow, you do not need to implement this dialog, but you should link to the mod.io Terms of Use and Privacy Policy in your Privacy Policy/EULA.

Example response

{
  "plaintext": "This game uses mod.io to support user-generated content. By selecting "I Agree" you agree to the mod.io Terms of Use and a mod.io account will be created for you (using your display name, avatar and ID). Please see the mod.io Privacy Policy on how mod.io processes your personal data.",
  "html": "<p>This game uses <a href="https://mod.io">mod.io</a> to support user-generated content. By selecting "I Agree" you agree to the mod.io <a href="https://mod.io/terms">Terms of Use</a> and a mod.io account will be created for you (using your  display name, avatar and ID). Please see the mod.io <a href="https://mod.io/privacy">Privacy Policy</a> on how mod.io processes your personal data.</p>",
  "buttons": {
    "agree": {
      "text": "I Agree"
    },
    "disagree": {
      "text": "No, Thanks"
    }
  },
  "links": {
    "website": {
      "text": "Website",
      "url": "https://mod.io",
      "required": false
    },
    "terms": {
      "text": "Terms of Use",
      "url": "https://mod.io/terms",
      "required": true
    },
    "privacy": {
      "text": "Privacy Policy",
      "url": "https://mod.io/privacy",
      "required": true
    },
    "manage": {
      "text": "Manage Account",
      "url": "https://mod.io/me/account",
      "required": false
    }
  }
}

Responses

Steam

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/steamauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  --data-urlencode 'appdata=NDNuZmhnaWdyaGdqOWc0M2o5eTM0aGc='

POST https://*.modapi.io/v1/external/steamauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/steamauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "appdata": "NDNuZmhnaWdyaGdqOWc0M2o5eTM0aGc="
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/steamauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/steamauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/steamauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/steamauth

Request an access token on behalf of a Steam user. To use this functionality you must add your games encrypted app ticket key from Steamworks, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.

HINT: If you want to overlay the mod.io site in-game on Steam, we recommend you add ?portal=steam to the end of the URL you open which will prompt the user to login with Steam. See Web Overlay Authentication for details. NOTE: Steam is the only authentication endpoint that requires their token to be base64 encoded. All other endpoints tokens should be provided as a UTF-8 character string.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Xbox Live

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/xboxauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'xbox_token=XBL3.0 x=9264027439329321064;eym72VygeZzTSUVRmNvw8v...'

POST https://*.modapi.io/v1/external/xboxauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/xboxauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "xbox_token": "XBL3.0 x=9264027439329321064;eym72VygeZzTSUVRmNvw8v..."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/xboxauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/xboxauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/xboxauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/xboxauth

Request an access token on behalf of an Xbox Live user. A Successful request will return an Access Token Object.

NOTE: To use this endpoint you will need to setup some additional settings prior to being able to authenticate Xbox Live users. For these instructions please contact us.

HINT: If you want to overlay the mod.io site in-game on Xbox, we recommend you add ?portal=xboxlive to the end of the URL you open which will prompt the user to login with Xbox Live. See Web Overlay Authentication for details.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

PlayStation™Network

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/psnauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'auth_code=MAXfj2TMqpHnaUMJdwCDbZUi2L3usnV7aw7xwHX2PEqT5hLkFF2VUyhlnCAMC0tQR3trpFQot0zvMMEtBzekilqeVD1Qm9nEcs9FljneaL3hCWPFSf6jjDSxOxOSytGD'

POST https://*.modapi.io/v1/external/psnauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/psnauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "auth_code": "MAXfj2TMqpHnaUMJdwCDbZUi2L3usnV7aw7xwHX2PEqT5hLkFF2VUyhlnCAMC0tQR3trpFQot0zvMMEtBzekilqeVD1Qm9nEcs9FljneaL3hCWPFSf6jjDSxOxOSytGD"
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/psnauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/psnauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/psnauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/psnauth

Request an access token on behalf of a PlayStation Network (PSN) user. A Successful request will return an Access Token Object.

NOTE: To use this endpoint you will need to setup some additional settings prior to being able to authenticate PlayStation users. For these instructions please contact us.

HINT: If you want to overlay the mod.io site in-game on PlayStation, we recommend you add ?portal=psn to the end of the URL you open which will prompt the user to login with PlayStation Network. See Web Overlay Authentication for details.

"PlayStation" and "DualSense" are registered trademarks or trademarks of Sony Interactive Entertainment Inc.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Nintendo Switch

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/switchauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'id_token=m72VygeZzTSUVRmNvw8v...'

POST https://*.modapi.io/v1/external/switchauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/switchauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "id_token": "m72VygeZzTSUVRmNvw8v..."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/switchauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/switchauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/switchauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/switchauth

Request an access token on behalf of a Nintendo Switch user. A Successful request will return an Access Token Object.

NOTE: To use this endpoint you will need to setup some additional settings prior to being able to authenticate Nintendo Switch users. For these instructions please contact us.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Meta Quest

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/oculusauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'device=rift' \
  -d 'nonce=m72VygeZzTSUVRmNvw8v...' \
  -d 'user_id=1829770514091149' \
  -d 'access_token=OCAf5kD1SbVNE...'

POST https://*.modapi.io/v1/external/oculusauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/oculusauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "device": "rift",
  "nonce": "m72VygeZzTSUVRmNvw8v...",
  "user_id": "1829770514091149",
  "access_token": "OCAf5kD1SbVNE..."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/oculusauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/oculusauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/oculusauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/oculusauth

Request an access token on behalf of an Meta Quest user. To use this functionality you must add your games AppId and secret from the Meta Quest Dashboard, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Epic Games

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/epicgamesauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'access_token=eym72VygeZzTSUVRmNvw8v...'

POST https://*.modapi.io/v1/external/epicgamesauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/epicgamesauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "access_token": "eym72VygeZzTSUVRmNvw8v..."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/epicgamesauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/epicgamesauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/epicgamesauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/epicgamesauth

Request an access token on behalf of an Epic Games user. A Successful request will return an Access Token Object.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

GOG Galaxy

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/galaxyauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  --data-urlencode 'appdata=GCL671bwZ/+zUeOWc0M'

POST https://*.modapi.io/v1/external/galaxyauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/galaxyauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "appdata": "GCL671bwZ/+zUeOWc0M"
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/galaxyauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/galaxyauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/galaxyauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/galaxyauth

Request an access token on behalf of a GOG Galaxy user. To use this functionality you must add your games encrypted app ticket key from GOG Galaxy, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Google

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/googleauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'id_token=eyJhbXciOiJIUzI1Lizs....'

POST https://*.modapi.io/v1/external/googleauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/googleauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "id_token": "eyJhbXciOiJIUzI1Lizs...."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/googleauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/googleauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/googleauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/googleauth

Request an access token on behalf of a Google user. A Successful request will return an Access Token Object.

NOTE: To use this endpoint you will need to setup some additional settings prior to being able to authenticate Google users. For these instructions please contact us.

HINT: If you want to overlay the mod.io site in-game on Android, we recommend you add ?portal=google to the end of the URL you open which will prompt the user to login with Google. See Web Overlay Authentication for details.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Discord

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/discordauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'discord_token=eyJhbXciOiJIUzI1Lizs....'

POST https://*.modapi.io/v1/external/discordauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/discordauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "discord_token": "eyJhbXciOiJIUzI1Lizs...."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/discordauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/discordauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/discordauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/discordauth

Request an access token on behalf of a Discord user. A Successful request will return an Access Token Object.

HINT: If you want to overlay the mod.io site in-game with Discord authentication, we recommend you add ?portal=discord to the end of the URL you open which will prompt the user to login with Discord. See Web Overlay Authentication for details.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

OpenID

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/external/openidauth?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'id_token=eyJhbXciOiJIUzI1Lizs....'

POST https://*.modapi.io/v1/external/openidauth?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/external/openidauth',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "id_token": "eyJhbXciOiJIUzI1Lizs...."
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/external/openidauth?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/external/openidauth', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/external/openidauth?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /external/openidauth

Request an access token on behalf of an OpenID identity provider. To use this method of authentication, you must configure the OpenID config in your game's authentication admin page. A Successful request will return an Access Token Object.

NOTE: The ability to authenticate players using your identity provider is a feature for advanced partners only. If you are interested in becoming an advanced partner, please contact us.

Example response

{
  "code": 200,
  "access_token": "eyJ0eXAiOiXKV1QibCJhbLciOiJeiUzI1.....",
  "date_expires": 1570673249
}

Responses

Email Exchange

Step 1 of 2

Example request

# You can also use wget
curl -X POST https://*.modapi.io/v1/oauth/emailrequest?api_key=YourApiKey \
  -H 'Content-Type: application/x-www-form-urlencoded' \ 
  -H 'Accept: application/json' \
  -d 'email=someperson@someservice.com'

POST https://*.modapi.io/v1/oauth/emailrequest?api_key=YourApiKey HTTP/1.1
Host: *.modapi.io
Content-Type: application/x-www-form-urlencoded
Accept: application/json

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://*.modapi.io/v1/oauth/emailrequest',
  method: 'post',
  data: '?api_key=YourApiKey',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');
const inputBody = '{
  "email": "someperson@someservice.com"
}';
const headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

fetch('https://*.modapi.io/v1/oauth/emailrequest?api_key=YourApiKey',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://*.modapi.io/v1/oauth/emailrequest', params={
  'api_key': 'YourApiKey'
}, headers = headers)

print r.json()

URL obj = new URL("https://*.modapi.io/v1/oauth/emailrequest?api_key=YourApiKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /oauth/emailrequest

Request a security code for a user, identified by their e-mail which can then be exchanged for an access token. To use this functionality you must use your games api_key from your games profile on mod.io. A Successful request will return a Message Object.

Example response