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

Prefilling user information

If you already know some of the user's details, you can pass them as additional query parameters on the authorization URL. If the user doesn't have an account yet, these values will prefill the signup form:

• email: Email address
• first_name: First name
• last_name: Last name
• country: Country code (ISO 3166-1 alpha-2, e.g. US, IN)
• birthday: Date of birth (YYYY-MM-DD)
• phone_number: Phone number

Example with prefill:

https://hca.dinosaurbbq.org/oauth/authorize?client_id=client_id&email=fiona%40example.com&first_name=Fiona&last_name=Hackworth&redirect_uri=redirect_uri&response_type=code&scope=email

These parameters are suggestions only — the user can edit any prefilled field before submitting. They are ignored for users who already have an account.

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!