Skip to main content

Initial Setup

How to setup DDB Importer.

Core Settings​

In Foundry look at the right hand side interface. Select the Settings (a cog icon) section and then click Configure Settings.

The settings dialogue will open. Select D&D Beyond Importer in the left hand menu to filter only the DDB Importer settings.

D&D Beyond Importer has many, many settings, however it tries to keep it's defaults set to things that new users to Foundry will need, so there is no need to go through them all now. They are described in the Settings Reference.

At the top of the DDB Importer settings click the Core setup button. This opens the DDB Importer Settings window. Click Start on the Info tab, or select the Core Settings tab. This section contains the only settings you really need to change before we get going any further.

(If this section won't open, see the FAQ)

The Core Settings tab is split into Cobalt Cookie, Campaign and Patreon tabs, and you can move between them with the Previous and Next buttons. Here we want to enter:

  • Our Cobalt Cookie so we can authenticate with D&DBeyond
  • Your D&D Beyond Campaign ID, if you are part of a campaign
  • A Patreon Key if you support me on Patreon

Cobalt Cookie

When DDB Importer talks to D&DBeyond it uses your authentication token to retrieve your characters and the content you have access to. Without this you're restricted to publicly accessible information

To get all your spells and do bulk importing you need to set the Cobalt Cookie setting to the value of your D&DBeyond CobaltSession cookie. See my helper Chrome extension to help.

Chrome Extension Retrieval​

  1. Follow the instructions to enable the extension.
  2. Open up D&D Beyond and log in.
  3. Navigate to a characters page.
  4. Click on the extension icon in the navigation bar and click the button to copy the cookie.
  1. Open up D&D Beyond and log in.
  2. Navigate to a characters page.
  3. Open up the developer console (try Command + Option + I, F12 or Control + Shift + I).
  4. Select the "Application" tab.
  5. Expand the "Cookies" section on the left hand side.
  6. Find and expand "https://www.dndbeyond.com"
  7. Enter CobaltSession into the search field (there are multiple Cobalt values, you want CobaltSession).
  8. Double click on the value field and copy the contents.

Cobalt Cookie Steps

Details for the curious​

Calls to D&D Beyond are proxied to provide authentication and to bypass CORS checks.

The proxy calls D&D Beyond with your credentials to fetch your data.

Do NOT give your cookie to other people, this is like handing out a password to your D&D Beyond account.

To logout/invalidate these credentials log out of your D&D Beyond Session.

Campaign ID​

Campaign ID

You do not need to set a campaign. It is only required if someone is sharing content with you via a D&D Beyond Campaign.

Click Fetch My Campaigns and select your campaign from the drop down. If automatic campaign detection is unavailable, a box appears where you can enter the campaign ID instead. This is the number at the end of the URL in the browser title bar when you are on the campaign page, NOT the URL to join the campaign.

Patreon Key or Custom Proxy (Optional)​

Many bits of DDB Importer are free. Some bits are locked behind Patreon support to help with the cost of running them and ongoing maintenance.

Without Patreon or Running your own Proxy you can:

  • Import Characters
  • Import Spells and Items
  • Import Adventures (it won't add monsters)

With Patreon Support or your own proxy (see below):

  • Import Monsters
  • Import Adventures (with monsters)

Patreon Supporter Exclusives:

  • Update back to D&D Beyond
  • Encounter Muncher
  • DDB Maps and Sticker import (Undying and higher tiers)
  • Character Class, Class Feature, Species, Background and Feat Compendium Sync (Undying and God tiers)
  • Priority Discord Support

Getting your Patreon Key​

Patreon Link

There are two ways to try and get a Patreon Key:

  1. Go to Activate to generate a key to enter.
  2. Click the "Detect Patreon Status" (sometimes temperamental).

In both cases you will be directed to log into Patreon.

Click Check Patreon Status to confirm your tier has been picked up.

Running your own proxy​

If you wish to host your own proxy, please see ddb-proxy. Please note support is not available for this mode, and it's feature set is limited.

Enter your proxy address on the Proxy tab of the DDB Importer Settings window and tick Use a custom proxy?.

You will be able to:

  • Import Characters
  • Import Spells, Items and Monsters
  • Import Adventures

I would recommend the following modules:

  • Tokenizer 2 or Tokenizer - Helps create pog style tokens from DDB art.
  • DAE - Helps enrich some of the effects for things like speed bonuses.
  • Aura Effects - Adds support for auras such as the Paladin's Aura of Protection. (Strongly recommended).
  • Vision/Detection Modes 5e - Adds some key missing vision and detection modes for 5e. (Strongly recommended).
  • Automated Conditions 5e - Helps with situational advantage and disadvantage. Mild Automation.