Login with Raidstrats

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.

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.

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.

Send someone to log in #

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

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

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.

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.

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

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 -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.

{
  "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.

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.

Authorization: Bearer ACCESS_TOKEN

curl https://raidstrats.gg/api/oauth/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "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.

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.

POST https://raidstrats.gg/api/oauth/v1/plans/PLAN_ID/embed
Authorization: Bearer ACCESS_TOKEN

{
  "id": "41824f15-5860-4ab4-9655-ba4736fa99a5",
  "name": "Mythic positions",
  "embedUrl": "https://raidstrats.gg/planner?embed=true&id=41824f15-5860-4ab4-9655-ba4736fa99a5&embed_key=..."
}

Stop access #

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

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