OAuth Guide

This guide will walk you through implementing OAuth 2.0 authentication with Hack Club Auth.

Step 1: Create an OAuth application

1. Navigate to the Developer Apps page
2. Click "app me up!"
3. Fill out the form with your app details and click "Create App"
4. Copy your Client ID and Client Secret and store them securely

Step 2: Redirect users to authorize your app

Construct an authorization URL with these parameters:

• client_id: Your Client ID from Step 1
• redirect_uri: One of the redirect URIs you configured
• response_type: code
• scope: Space-separated list of requested scopes

Example authorization URL:

GET https://hca.dinosaurbbq.org/oauth/authorize?client_id=client_id&redirect_uri=redirect_uri&response_type=code&scope=email

Step 3: Handle the authorization callback

After the user authorizes your app, they'll be redirected to your redirect URI with an authorization code:

https://yourapp.com/callback?code=abc123def456

Step 4: Exchange the code for an access token

Make a POST request to exchange the authorization code for an access token:

POST https://hca.dinosaurbbq.org/oauth/token

Request body:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://yourapp.com/callback",
  "code": "abc123def456",
  "grant_type": "authorization_code"
}

Response:

{
  "access_token": "idntk.mraowj2z72e1x8i2a60o88j3h7d0f1",
  "token_type": "Bearer",
  "expires_in": 15778800,
  "refresh_token": "idnrf.abc123xyz789...",
  "scope": "openid profile"
}

Store both tokens securely - you'll use the access token to authenticate API requests, and the refresh token to obtain new access tokens.

Refreshing Access Tokens

Access tokens expire after 6 months. Use the refresh token to obtain a new access token without requiring user interaction:

POST https://hca.dinosaurbbq.org/oauth/token

Request body:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "idnrf.abc123xyz789...",
  "grant_type": "refresh_token"
}

Response:

{
  "access_token": "idntk.new_access_token...",
  "token_type": "Bearer",
  "expires_in": 15778800,
  "refresh_token": "idnrf.new_refresh_token...",
  "scope": "openid profile"
}

Step 5: Make authenticated API requests

Include the access token in the Authorization header when making requests to the Hack Club Auth API:

Authorization: Bearer idntk.mraowj2z72e1x8i2a60o88j3h7d0f1

Your first endpoint will probably be GET /api/v1/me
This is analogous to users.info if you're coming from a Slack API background.

Happy hacking!