GET & POST /oauth

Supported formats: json

Writing data for a user requires a valid access token. We support OAuth 2.0 to get user access tokens.

If you're not familiar with OAuth 2.0 You can get a sense of the workflow and read more about how it works in the official documentation here.

What It Looks Like

Here's the quick overview of what the workflow is like

1. Your user clicks a "Connect to BGA" button
2. Then they get sent to Board Game Atlas to securely log in.
3. They're sent back to your app after login and you can start writing user data.

Get The Access Token

Whether your making a web or mobile app, you will need to have a server to be able to use OAuth to get the access_token for the user.

1. GET https://api.boardgameatlas.com/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_for_auth_code

   Start with using this URL for a "Connect to Board Game Atlas" button or link. Just swap out your_client_id with your actual id and your_redirect_for_auth_code with the uri that will handle the next step. It's what brings the user to BGA to sign in and authorize your app.

2. GET http://your_website.com?code=the_code_you_just_got

   After they sign in, Board Game Atlas will redirect to your_redirect_for_auth_code. In the query there will now be a code parameter ('the_code_you_just_got'). It's the authorization code to use in the next step.

3. POST https://api.boardgameatlas.com/oauth/token 
   HEADERS content-type: application/x-www-form-urlencoded
   BODY client_id = your_client_id
        client_secret = your_client_secret
        code = the_code_you_just_got
        redirect_uri = your_redirect_for_auth_code
        grant_type = "authorization_code"

   Using the authorization code that was sent to you, make this POST to get the access token.

4. The response to that request will look like this

   { 
      access_token: '2e206e5b5eks3bps5ca699500160e81dd7f60fa',
      token_type: 'Bearer',
      expires_in: 3599,
      refresh_token: '075050363b14l696e6aaf4b6f1b0786f2fe6813' 
   }

That's it! Now you use the access_token to make all the user requests you want. It will expire in 1 hour though so you'll need to handle what happens at that point too. That's what the refresh_token is for.

Refreshing Your Token

The access_token will expire in 1 hour. Use the refresh token to get a new one.

POST https://api.boardgameatlas.com/oauth/token 
HEADERS content-type: application/x-www-form-urlencoded
BODY client_id = your_client_id
     client_secret = your_client_secret
     refresh_token = your_refresh_token
     grant_type = "refresh_token"

The refresh token lasts 2 weeks before expiring. When you use it, the previous access_token is invalidated and you are given a new one for that user.