OAUTH.md

Destiny.gg Authentication

OAuth style authentication integration.

THIS GUIDE IS INCOMPLETE

First thing to do

• Register an application in your destiny.gg profile if you haven't.
• Copy the ID (client_id) and Secret from your application

TLDR

• Send user to authorize url /oauth/authorize, the user logs in...
• Get response code from the URL then do a token exchange /oauth/token api call for an access_token
• Use the access token to get the user info /api/userinfo?token=x8yf[...]f0c

Authorize

Request

GET https://www.destiny.gg/oauth/authorize

Parameter	Value
response_type	must be "code" - indicates that you expect to receive an authorization code
client_id	The client ID you received when you first created the application
redirect_uri	Indicates the URL to return to after authorization is complete, such as org.example.app://redirect
state	Arbitrary alphanumeric string that you'll send and then verify, max 64 characters long.
code_challenge	The code challenge generated as described below

Code Challenge

let secret = hash("sha256", CLIENT_SECRET)
let code_verifier = 'Fwef[...]8ehyf9' //  Random URL-safe string with a minimum length of 43 characters.
let code_challenge = base64_encode(hash("sha256", code_verifier + secret))

Response

Destiny.gg will issue a 302 redirect to the url specified in the redirect_uri with the state and code parameters.

Location: org.example.app://redirect?state=...&code=...

You should check that the state against the initial value.

The code can then be used to do a token exchange.

Token Exchange

Exchange your authorization code for an access_token

Request

GET https://www.destiny.gg/oauth/token

Parameter	Value
grant_type	Must be "authorization_code"
code	The client will send the authorization code it obtained in the redirect
client_id	The application’s registered client ID
redirect_uri	The redirect URL that was used in the initial authorization request
code_verifier	The code verifier portion used in the initial /oauth/authorize endpoint (see above would be 'Fwef[...]8ehyf9')

Response

{
    "access_token" : "VdD03YOa2GYbjfnpZm0hhzb7OeyvO5Fp5lWOQbFlYGKQ4MVN1iEZcmwJh5VBFhYf",
    "refresh_token" : "kWGB9cxqxUJXsHDA2S0rbOaqStaxEmPu1R0Eu9kqkchMXnu34shGYYcH3iDIqE7R",
    "expires_in" : 3600,
    "scope" : "identify",
    "token_type" : "bearer"
}

Renew Token

When an access_token expires, you will receive the following error

{
    "error" : "token_expired",
    "message" : "The token has expired.",
    "code" : 403
}

Request

GET https://www.destiny.gg/oauth/token

Parameter	Value
grant_type	Must be "refresh_token"
client_id	The application’s registered client ID
refresh_token	The refresh token

The response is the same as the token exchange response.