Raidstrats.gg Developers Login

Login with Raidstrats

Create an app, choose what it can see, and let people approve access with their Raidstrats account.

client_id and secret People approve each login Embed docs

Your apps #

Give it a name and a return address, then pick what people share.

Access you've given #

These are apps you allowed to use your Raidstrats account. Removing one stops it from reading your data.

Log in to see apps you have allowed.

Setup #

  1. Create an app and choose the data it needs. It stays off until an admin approves it.
  2. Copy the client_id and secret. The secret is shown once. Keep it on your server, not in a browser or addon.
  3. Send the person to the login URL below. That URL is opened in their browser.
  4. Raidstrats asks them to log in, then shows what your app will see.
  5. Their browser returns to your site with a one-time code. That code is not the bearer token.
  6. Your server POSTs that code to /oauth/token. The JSON field access_token is the bearer token.
  7. Call the data URLs with Authorization: Bearer ACCESS_TOKEN.
A public plan can be embedded without this login. After someone connects, a private guild plan can be shown on your site to the people you allow, such as a group. The normal plan link stays locked. The embed guide is separate: embed docs.

Data access #

You choose these when you create the app. A login can only ask for data the app was given. The person still has to approve it.

profile

Username

Always included. Display name and account id.

character

Character

Linked in-game name, realm, region, and class.

guild

Guild

Guild name and rank.

plans

Plans

Plans that person created, plus guild plans they can open. Each guild plan includes an embed link. The drawing stays in the embed.

addon

In-game import

The in-game import text for plans that person created, and guild plans they can open. Ask for plans as well if you also need the plan list.

rosters

Rosters

Names, links, and players for rosters that person created.

replays

Log Replays

Warcraft Logs reports that person built on Log Replay, their pulls, and embed links. Private reports they can watch come with a private embed link. With Heroic Raider or higher, your app can also build new logs for them.

patreon

Patreon tier

That person's Raidstrats Patreon tier, so you can show or hide features they have.

Send someone to log in #

Open this URL in their browser. Replace the values with your app.

URL
https://raidstrats.gg/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=profile%20plans&state=RANDOM_STATE
response_typeRequired
code
client_idRequired
Your client_id.
redirect_uriRequired
A return address saved on the app, copied exactly. http://localhost:8000/auth/callback and http://localhost:8000/oauth/callback are different. Localhost may use http. Every other site must use https.
scopeOptional
A space-separated list, such as profile guild plans. Username is included even when this is left off. Asking for data the app was not given is rejected.
stateRequired
A random string of at least 8 characters. Check that the same value comes back, so you know the reply belongs to this login.
promptOptional
Use consent to show the approval page again even if they already allowed the app.
code_challengeOptional
URL-safe base64 SHA-256 of a random code_verifier you keep on your server. If you send this, the token request must send that same verifier.
code_challenge_methodWith the challenge
S256. Required whenever code_challenge is sent.

If they approve, their browser is sent to your return address. The code is a one-time login code. It is not the bearer token.

Browser returns here
https://example.com/callback?code=ONE_TIME_CODE&state=RANDOM_STATE

If they cancel, the URL contains error=access_denied instead of a code. The code expires after 5 minutes and works once. Save it and continue to the next step from your server.

Get the bearer token #

The bearer token is created only when your server trades the login code. Opening /oauth/token in a browser does not create one.

  1. The person approves, and their browser arrives at your return address with code.
  2. Your server POSTs that code to https://raidstrats.gg/oauth/token.
  3. Read access_token from the JSON reply. That value, starting with rsoat_, is the bearer token.
  4. Send it on later requests as Authorization: Bearer ACCESS_TOKEN.
Put the fields in the POST body, not in the URL. client_id, client_secret, code, and redirect_uri are read from the form body only. A link such as /oauth/token?client_id=...&client_secret=... does not send them, so the reply says the client_id and secret were not received. Never put the secret in a URL.
POST body
POST https://raidstrats.gg/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=ONE_TIME_CODE
&redirect_uri=https://example.com/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&code_verifier=CODE_VERIFIER
grant_typeRequired
authorization_code for the first token. refresh_token later.
codeRequired
The one-time code from the return address. Not the bearer token.
redirect_uriRequired
The same return address used in the login URL, and one saved on the app. The path has to match.
client_idRequired
The public id from the app, such as rs_....
client_secretRequired
The secret shown once when the app was created. Send it from your server only.
code_verifierWhen a challenge was used
The original random string whose SHA-256 you sent as code_challenge. Leave it off only if the login URL had no challenge. A wrong or missing verifier does not create a bearer token.

You can send the client_id and secret as Basic authentication instead of body fields. Encode client_id:client_secret in base64 and send Authorization: Basic .... The other fields still go in the POST body.

curl
curl -X POST https://raidstrats.gg/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=ONE_TIME_CODE" \
  -d "redirect_uri=https://example.com/callback" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

A successful reply looks like this. Copy access_token. That is the bearer token. Raidstrats keeps only a hash of it, so it cannot be read back out of the database later.

JSON
{
  "access_token": "rsoat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rsort_...",
  "scope": "plans profile"
}

The bearer token lasts 1 hour. The refresh token lasts 30 days. Refresh from your server with another POST. Each refresh replaces the old refresh token.

Refresh
POST https://raidstrats.gg/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

Read data #

Use the bearer token from access_token. Send it on each request. The site login cookie is not accepted here.

Header
Authorization: Bearer ACCESS_TOKEN
GET /api/oauth/v1/meAny allowed data
Account id and username, plus character or guild when those were approved. With patreon: patreon.tier (lfr_raider, normal_raider, heroic_raider, mythic_raider, max_raider or null) and patreon.name. With replays: replays.canBuild (show your Build button only when true) and replays.warcraftLogsConnected (needed for private logs).
GET /api/oauth/v1/plansplans
Plans that person created, and guildPlans they can open. A private guild plan includes an embedUrl for your group page. The normal plan link does not open it for other people.
GET /api/oauth/v1/plans/PLAN_ID/thumbnailplans
The preview image for one plan they created, or a guild plan they can open. thumbnail is a link, or null when that plan has no preview yet.
GET /api/oauth/v1/plans/PLAN_ID/addon-exportaddon
The in-game import string for one plan they created, or a guild plan they can open. The string starts with !raidstrats-addon-.
POST /api/oauth/v1/plans/addon-exportaddon
The same string for several plans. Body: { "planIds": ["id", "id"] }, up to 50. Each plan is reported on its own, so one missing plan does not fail the rest.
GET /api/oauth/v1/rostersrosters
Their rosters, with a player count.
GET /api/oauth/v1/rosters/LINK_IDrosters
One roster they created, including players.
GET /api/oauth/v1/replaysreplays
Warcraft Logs reports they built on Log Replay, newest first, with pullCount, kills, readyPulls, a url and an embedUrl for the newest pull that is ready (null if none is yet). Optional ?limit= up to 50. Private reports are only listed while they can still watch them.
POST /api/oauth/v1/replaysreplays
Build a log for that person, the same as opening it on Raidstrats. Send JSON { "log": "https://www.warcraftlogs.com/reports/CODE", "pulls": "all" }. pulls can be "all" (default), "kills" or a list of pull ids. Up to 60 new pulls per build. Needs Heroic Raider or higher (403 tier_required otherwise). Private logs need them to have connected Warcraft Logs on Raidstrats (403 wcl_private with a connectUrl). One build at a time per person (409 build_running). Returns 202 with building (pulls queued) and alreadyReady, then builds in the background. Follow it with the GET below: build.status goes from building to done, and each pull's ready turns true when it can be embedded.
GET /api/oauth/v1/replays/REPORT_CODEreplays
One built report with every pull: boss, difficulty, kill, boss percent, duration, ready, url and embedUrl. Only embed pulls where ready is true. Those are already on Raidstrats, so anyone can watch them. A pull that is not ready shows a "not opened yet" message until someone with access opens it on Raidstrats. Works for any public report that was built on Log Replay. For a private report, the embedUrl includes a private embed_key that only your app gets. Anyone with that link can watch the pull, so only show it to people who should see it. It stops working when they remove your app or can no longer watch the report.
curl
curl https://raidstrats.gg/api/oauth/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"
JSON
{
  "sub": "42",
  "scope": "guild profile",
  "username": "Nairyana",
  "createdAt": 1710000000000,
  "guild": { "name": "Example Guild", "rank": "Raider", "rankId": 4 }
}

Plan and roster lists accept limit (up to 100) and offset. Guild plans use the same guild access as on Raidstrats, up to 100. The list does not include the drawing. People who only have the normal plan link still cannot open a private guild plan. If that person removes the app, or can no longer open the plan, the group embed stops working.

Show a guild plan

Use embedUrl as the iframe address. Do not take the plan id out and build a new link. The private key is already inside embedUrl.

JavaScript
const res = await fetch('https://raidstrats.gg/api/oauth/v1/plans', {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const data = await res.json();
const plan = data.guildPlans[0];

iframe.src = plan.embedUrl;

If someone pastes a normal plan link, read the id from it and ask for an embed link. Then use that embedUrl the same way.

HTTP
POST https://raidstrats.gg/api/oauth/v1/plans/PLAN_ID/embed
Authorization: Bearer ACCESS_TOKEN
JSON
{
  "id": "41824f15-5860-4ab4-9655-ba4736fa99a5",
  "name": "Mythic positions",
  "embedUrl": "https://raidstrats.gg/planner?embed=true&id=41824f15-5860-4ab4-9655-ba4736fa99a5&embed_key=..."
}

Plan preview image

Use a plan id from the plan list, or from a plan link. This needs the plans permission. The image is the same preview shown on Raidstrats. If the plan has never been saved with a preview, thumbnail is null.

HTTP
GET https://raidstrats.gg/api/oauth/v1/plans/PLAN_ID/thumbnail
Authorization: Bearer ACCESS_TOKEN
JSON
{
  "id": "41824f15-5860-4ab4-9655-ba4736fa99a5",
  "name": "Mythic positions",
  "thumbnail": "https://cdn.raidstrats.gg/userPlanImages/…"
}

In-game import text

Ask for addon on the login URL, such as scope=profile plans addon. The person has to approve it. This is separate from embed links. The text is created when the plan is saved on Raidstrats. If it has never been saved since that text was added, the reply is addon_export_missing until someone opens the plan and saves it.

HTTP
GET https://raidstrats.gg/api/oauth/v1/plans/PLAN_ID/addon-export
Authorization: Bearer ACCESS_TOKEN
JSON
{
  "id": "41824f15-5860-4ab4-9655-ba4736fa99a5",
  "name": "Mythic positions",
  "addonExport": "!raidstrats-addon-…"
}

For several plans, POST the ids. A plan this account cannot open, or a plan with no saved import text, comes back in results with ok: false. The other plans are still included.

HTTP
POST https://raidstrats.gg/api/oauth/v1/plans/addon-export
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{ "planIds": ["PLAN_ID", "OTHER_PLAN_ID"] }

Stop access #

The person can remove an app from this page. Your server can also revoke a token.

HTTP
POST https://raidstrats.gg/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=ACCESS_OR_REFRESH_TOKEN
&token_type_hint=refresh_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
Creating a new secret stops the old secret from trading codes. Turning an app off, or deleting it, stops its tokens from reading data. People must approve the login again before an app can see something new.