### Install better-auth npm package

Source: https://auth.hackclub.com/docs/oidc-guide

Command to install the 'better-auth' npm package, a TypeScript authentication library used for integrating OIDC providers.

```bash
npm i better-auth
```

--------------------------------

### Configure better-auth client plugin (TypeScript)

Source: https://auth.hackclub.com/docs/oidc-guide

Example of configuring the 'better-auth' client-side to use the generic OAuth client plugin. This setup is necessary for the client to interact with the OIDC provider.

```typescript
// auth-client.ts
import { createAuthClient } from "better-auth/client"
import { genericOAuthClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
  plugins: [genericOAuthClient()],
})

```

--------------------------------

### Example ID Token Claims

Source: https://auth.hackclub.com/docs/oidc-guide

An example of the claims found within an ID token when specific scopes (openid, profile, email, verification_status) are requested. This JSON object contains user identification and verification details.

```JSON
{
  "iss": "https://auth.hackclub.com",
  "sub": "ident!sdfjksfjd",
  "aud": "your_client_id",
  "exp": 1700000000,
  "iat": 1699996400,
  "name": "Heidi Trashworth",
  "given_name": "Heidi",
  "family_name": "Trashworth",
  "email": "racc@garbagemail.biz",
  "email_verified": true,
  "verification_status": "verified",
  "ysws_eligible": true
}
```

--------------------------------

### GET /oauth/authorize

Source: https://auth.hackclub.com/docs/oauth-guide

Redirects the user to the Hack Club authorization page to grant your application access to their account.

```APIDOC
## GET /oauth/authorize

### Description
Redirects the user to the Hack Club authorization server to initiate the OAuth 2.0 flow.

### Method
GET

### Endpoint
https://auth.hackclub.com/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your application's Client ID.
- **redirect_uri** (string) - Required - The URL where the user will be redirected after authorization.
- **response_type** (string) - Required - Must be set to "code".
- **scope** (string) - Required - Space-separated list of requested scopes (e.g., "openid profile email").

### Request Example
GET https://auth.hackclub.com/oauth/authorize?client_id=your_id&redirect_uri=https://yourapp.com/callback&response_type=code&scope=email
```

--------------------------------

### POST /oauth/token

Source: https://auth.hackclub.com/docs/oauth-guide

Exchanges an authorization code or a refresh token for a new access token.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code for an access token or uses a refresh token to obtain a new access token.

### Method
POST

### Endpoint
https://auth.hackclub.com/oauth/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's Client ID.
- **client_secret** (string) - Required - Your application's Client Secret.
- **grant_type** (string) - Required - Either "authorization_code" or "refresh_token".
- **code** (string) - Optional - Required if grant_type is "authorization_code".
- **refresh_token** (string) - Optional - Required if grant_type is "refresh_token".
- **redirect_uri** (string) - Optional - Required if grant_type is "authorization_code".

### Request Example
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "code": "abc123def456",
  "grant_type": "authorization_code"
}

### Response
#### Success Response (200)
- **access_token** (string) - The token used for API requests.
- **token_type** (string) - Typically "Bearer".
- **expires_in** (integer) - Lifetime of the token in seconds.
- **refresh_token** (string) - Token used to obtain new access tokens.

### Response Example
{
  "access_token": "idntk.mraowj2z72e1x8i2a60o88j3h7d0f1",
  "token_type": "Bearer",
  "expires_in": 15778800,
  "refresh_token": "idnrf.abc123xyz789..."
}
```

--------------------------------

### Sign in using Hack Club OIDC with better-auth (TypeScript)

Source: https://auth.hackclub.com/docs/oidc-guide

Example of initiating the sign-in flow using the 'better-auth' client. This function directs the user to the Hack Club OAuth provider and specifies the callback URL.

```typescript
await authClient.signIn.oauth2({
  providerId: "hackclub",
  callbackURL: "/dashboard",
})

```

--------------------------------

### GET /api/v1/identities

Source: https://auth.hackclub.com/docs/api

Retrieves a list of all identities that have authorized the application. Requires a program key for authentication.

```APIDOC
## GET /api/v1/identities

### Description
List all identities that have authorized your application.

### Method
GET

### Endpoint
/api/v1/identities

### Parameters
#### Query Parameters
- **program_key** (string) - Required - Program key for authentication.

### Request Example
```
GET /api/v1/identities?program_key=YOUR_PROGRAM_KEY
```

### Response
#### Success Response (200)
- **identities** (array) - A list of identity objects.
  - **id** (string) - The unique identifier for the identity.
  - **first_name** (string) - The first name of the identity.
  - **last_name** (string) - The last name of the identity.

#### Response Example
```json
{
  "identities": [
    {
      "id": "ident!Rm8fEo",
      "first_name": "Heidi",
      "last_name": "Latta"
    },
    {
      "id": "ident!D2af2B",
      "first_name": "Heidi",
      "last_name": "Wofford"
    }
  ]
}
```
```

--------------------------------

### Construct Authorization URL

Source: https://auth.hackclub.com/docs/oauth-guide

Build the URL to redirect users to Hack Club Auth for app authorization. Requires your Client ID, a configured redirect URI, response type 'code', and requested scopes.

```URL
GET https://auth.hackclub.com/oauth/authorize?client_id=client_id&redirect_uri=redirect_uri&response_type=code&scope=email
```

--------------------------------

### Configure better-auth with Hack Club OIDC Provider (TypeScript)

Source: https://auth.hackclub.com/docs/oidc-guide

Example of configuring the 'better-auth' server-side to use Hack Club as a generic OAuth OIDC provider. It requires setting up the providerId, discoveryUrl, clientId, clientSecret, and desired scopes.

```typescript
// auth.ts
import { betterAuth } from "better-auth"
import { genericOAuth } from "better-auth/plugins"

export const auth = betterAuth({
  // ...your other config
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: "hackclub",
          discoveryUrl: "https://auth.hackclub.com/.well-known/openid-configuration",
          clientId: process.env.HACKCLUB_CLIENT_ID,
          clientSecret: process.env.HACKCLUB_CLIENT_SECRET,
          scopes: ["openid", "profile", "email", "verification_status"],
        },
      ],
    }),
  ],
})

```

--------------------------------

### GET /api/v1/me

Source: https://auth.hackclub.com/docs/api

Retrieves the authenticated user's identity information based on granted scopes. Requires an OAuth access token in the Authorization header.

```APIDOC
## GET /api/v1/me

### Description
Get the authenticated user's identity information based on granted scopes.

### Method
GET

### Endpoint
/api/v1/me

### Authentication
Required (OAuth access token in `Authorization: Bearer <token>` header)

### Response
#### Success Response (200)
- **identity** (object) - User's identity details.
  - **id** (string) - User's unique identifier.
  - **ysws_eligible** (boolean) - Whether the user is eligible for YSWS.
  - **verification_status** (string) - The current verification status (`needs_submission`, `pending`, `verified`, `ineligible`).
  - **first_name** (string) - User's first name.
  - **last_name** (string) - User's last name.
  - **primary_email** (string) - User's primary email address.
  - **slack_id** (string) - User's Slack ID.
  - **phone_number** (string) - User's phone number.
  - **birthday** (string) - User's birthday in YYYY-MM-DD format.
  - **legal_first_name** (string) - User's legal first name.
  - **legal_last_name** (string) - User's legal last name.
  - **addresses** (array) - List of user's addresses.
    - **id** (string) - Address ID.
    - **first_name** (string) - First name associated with the address.
    - **last_name** (string) - Last name associated with the address.
    - **line_1** (string) - Address line 1.
    - **line_2** (string) - Address line 2.
    - **city** (string) - City.
    - **state** (string) - State.
    - **postal_code** (string) - Postal code.
    - **country** (string) - Country.
    - **phone_number** (string) - Phone number associated with the address.
    - **primary** (boolean) - Whether this is the primary address.
- **scopes** (array) - List of granted scopes.

#### Response Example
```json
{
  "identity": {
    "id": "ident!Gjfr0w",
    "ysws_eligible": true,
    "verification_status": "needs_submission",
    "first_name": "Heidi",
    "last_name": "Trashworth",
    "primary_email": "heidi897@hackclub.com",
    "slack_id": "U00000897",
    "phone_number": "+18028675309",
    "birthday": "2005-06-15",
    "legal_first_name": "Hakkuun",
    "legal_last_name": "[WOULDN'T YOU LIKE TO KNOW]",
    "addresses": [
      {
        "id": "addr!y0Xu5D",
        "first_name": "Helena",
        "last_name": "Ackfoundation",
        "line_1": "8605 Santa Monica Blvd",
        "line_2": "PMB 86294",
        "city": "West Hollywood",
        "state": "CA",
        "postal_code": "90069",
        "country": "US",
        "phone_number": "+18028675309",
        "primary": true
      }
    ]
  },
  "scopes": [
    "email",
    "name",
    "verification_status",
    "slack_id",
    "basic_info",
    "address",
    "legal_name"
  ]
}
```
```

--------------------------------

### Exchange Code for Access Token

Source: https://auth.hackclub.com/docs/oauth-guide

Send a POST request to exchange an authorization code for an access token and refresh token. This requires your client ID, client secret, redirect URI, the authorization code, and 'authorization_code' grant type.

```HTTP Request
POST https://auth.hackclub.com/oauth/token

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

--------------------------------

### Authenticate API Requests

Source: https://auth.hackclub.com/docs/oauth-guide

Include the obtained access token in the 'Authorization' header as a Bearer token to make authenticated requests to the Hack Club Auth API.

```HTTP Header
Authorization: Bearer idntk.mraowj2z72e1x8i2a60o88j3h7d0f1
```

--------------------------------

### GET /api/external/check

Source: https://auth.hackclub.com/docs/api

Checks the verification status of a user by their ID, email, or Slack ID. This is a public endpoint and does not require authentication.

```APIDOC
## GET /api/external/check

### Description
Check the verification status of a user by their ID, email, or Slack ID. This is a public endpoint that doesn't require authentication.

### Method
GET

### Endpoint
/api/external/check

### Query Parameters
- **idv_id** (string) - Required (one of `idv_id`, `email`, or `slack_id`) - User's public ID (format: `ident!xxxxx`).
- **email** (string) - Required (one of `idv_id`, `email`, or `slack_id`) - User's email address.
- **slack_id** (string) - Required (one of `idv_id`, `email`, or `slack_id`) - User's Slack ID.

### Response
#### Success Response (200)
- **result** (string) - The verification status (`needs_submission`, `pending`, `verified_eligible`, `verified_but_over_18`, `rejected`, `not_found`).

#### Response Example
```json
{
  "result": "verified_eligible"
}
```
```

--------------------------------

### GET /api/v1/identities/:id

Source: https://auth.hackclub.com/docs/api

Retrieves a specific user's identity by their public ID. This endpoint requires a program key for authentication and is intended for HQ official programs.

```APIDOC
## GET /api/v1/identities/:id

### Description
Get a specific user's identity by their public ID. This endpoint is available only when using a program key.

### Method
GET

### Endpoint
/api/v1/identities/:id

### Path Parameters
- **id** (string) - Required - The user's public ID (e.g., `ident!abc123`).

### Authentication
Program key required (in `Authorization: Bearer prgmk.<key>` header)

### Response
#### Success Response (200)
- **identity** (object) - User's identity details. Fields returned depend on the program's configured scopes.
  - **id** (string) - User's unique identifier.
  - **first_name** (string) - User's first name.
  - **last_name** (string) - User's last name.

#### Response Example
```json
{
  "identity": {
    "id": "ident!EOfd6qd",
    "first_name": "Heidi",
    "last_name": "Hacksworth"
  }
}
```
```

--------------------------------

### Refresh Access Token

Source: https://auth.hackclub.com/docs/oauth-guide

Use a refresh token to obtain a new access token without user interaction. This POST request requires your client ID, client secret, the refresh token, and 'refresh_token' grant type.

```HTTP Request
POST https://auth.hackclub.com/oauth/token

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

--------------------------------

### Authenticate API Requests

Source: https://auth.hackclub.com/docs/api

Demonstrates how to include an OAuth access token or a program key in the Authorization header for authenticated API requests.

```HTTP
Authorization: Bearer idntk.mraowj2z72e1x8i2a60o88j3h7d0f1
Authorization: Bearer prgmk.abc123def456...
```

--------------------------------

### List Identities (API)

Source: https://auth.hackclub.com/docs/api

This API endpoint retrieves a list of all identities that have authorized your application. It requires a program key for authentication and returns a JSON array of identity objects, each containing an ID, first name, and last name.

```http
GET /api/v1/identities
```

```json
{
  "identities": [
    {
      "id": "ident!Rm8fEo",
      "first_name": "Heidi",
      "last_name": "Latta"
    },
    {
      "id": "ident!D2af2B",
      "first_name": "Heidi",
      "last_name": "Wofford"
    }
  ]
}
```

--------------------------------

### Handle API Error Responses

Source: https://auth.hackclub.com/docs/api

Standard error response format returned by the API when a request fails due to authorization issues, missing resources, or invalid parameters.

```JSON
{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}
```

--------------------------------

### OIDC Discovery

Source: https://auth.hackclub.com/docs/oidc-guide

Retrieve the OIDC discovery document which contains all endpoints and capabilities of the OIDC implementation. This is useful for auto-configuring OIDC libraries.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Fetches the OIDC discovery document, providing configuration details for the authentication server.

### Method
GET

### Endpoint
`/.well-known/openid-configuration`

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **object** - The OIDC discovery document containing various endpoints and capabilities.
```

--------------------------------

### OIDC Reauthentication with prompt=login

Source: https://auth.hackclub.com/docs/oidc-guide

Force user re-authentication by adding the `prompt=login` parameter to the authorization request. This ensures the user actively re-verifies their identity, even with an active session.

```HTTP
GET https://auth.hackclub.com/oauth/authorize?client_id=your_client_id&prompt=login&redirect_uri=https%3A%2F%2Farcade.hackclub.com%2Fauth%2Fcallback&response_type=code&scope=openid
```

--------------------------------

### User Info Endpoint

Source: https://auth.hackclub.com/docs/oidc-guide

Retrieve user claims by making a request to the userinfo endpoint, including the access token in the Authorization header.

```APIDOC
## GET /oauth/userinfo

### Description
Fetches user claims (profile information) associated with the provided access token.

### Method
GET

### Endpoint
`/oauth/userinfo`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer idntk.abc123...`).

### Request Example
```
Authorization: Bearer idntk.abc123...
```

### Response
#### Success Response (200 OK)
- **object** - A JSON object containing user claims based on the granted scopes.
```

--------------------------------

### OIDC Discovery Endpoint

Source: https://auth.hackclub.com/docs/oidc-guide

Retrieve the OIDC discovery document which contains all endpoints and capabilities of the OIDC implementation. This is typically used by OIDC libraries to auto-configure themselves.

```HTTP
GET /.well-known/openid-configuration
```

--------------------------------

### OIDC Address Claim Format

Source: https://auth.hackclub.com/docs/oidc-guide

The structure of the address claim when the 'address' scope is granted. This follows the OIDC standard format for representing a user's address information.

```JSON
{
  "address": {
    "street_address": "15 Falls Road",
    "locality": "Shelburne",
    "region": "VT",
    "postal_code": "05482",
    "country": "US"
  }
}
```

--------------------------------

### OAuth Authorization Request

Source: https://auth.hackclub.com/docs/oidc-guide

Redirect users to the authorization server to initiate the OAuth 2.0 flow. This step requests user consent for accessing their information.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the OAuth 2.0 authorization code flow by redirecting the user to the authorization server.

### Method
GET

### Endpoint
`https://auth.hackclub.com/oauth/authorize`

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your application's client ID.
- **redirect_uri** (string) - Required - The URI to redirect the user back to after authorization.
- **response_type** (string) - Required - Must be set to `code` for the authorization code flow.
- **scope** (string) - Optional - A space-delimited list of scopes to request (e.g., `openid profile email`).
- **prompt** (string) - Optional - If set to `login`, forces the user to re-authenticate.
- **max_age** (integer) - Optional - Maximum age in seconds for the user's session before reauthentication is required.

### Request Example
```
GET https://auth.hackclub.com/oauth/authorize?client_id=your_client_id&redirect_uri=https%3A%2F%2Farcade.hackclub.com%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email
```

### Response
#### Success Response (302 Found)
- **Location header** - Redirects the user to the authorization server.

#### Error Response
- **400 Bad Request** - If required parameters are missing or invalid.
```

--------------------------------

### Retrieve Specific User Identity via Program Key

Source: https://auth.hackclub.com/docs/api

Retrieves identity information for a specific user using a program key. This endpoint is restricted to HQ official programs.

```JSON
{
  "identity": {
    "id": "ident!EOfd6qd",
    "first_name": "Heidi",
    "last_name": "Hacksworth"
  }
}
```

--------------------------------

### OIDC User Info Endpoint

Source: https://auth.hackclub.com/docs/oidc-guide

Retrieve additional user claims from the userinfo endpoint by including the access token in the Authorization header. This allows you to fetch details beyond what's in the ID token.

```HTTP
GET /oauth/userinfo

Authorization: Bearer idntk.abc123...
```

--------------------------------

### Check User Verification Status

Source: https://auth.hackclub.com/docs/api

A public endpoint to check the verification status of a user using their ID, email, or Slack ID. No authentication is required for this request.

```JSON
{
  "result": "verified_eligible"
}
```

--------------------------------

### Token Exchange

Source: https://auth.hackclub.com/docs/oidc-guide

Exchange the authorization code received after user consent for an access token and an ID token. This is a crucial step for authentication.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code for an access token and an ID token.

### Method
POST

### Endpoint
`https://auth.hackclub.com/oauth/token`

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
- **redirect_uri** (string) - Required - The redirect URI used in the authorization request.
- **code** (string) - Required - The authorization code received from the `/oauth/authorize` endpoint.
- **grant_type** (string) - Required - Must be set to `authorization_code`.

### Request Example
```json
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://arcade.hackclub.com/auth/callback",
  "code": "a1b2c3d4e5f6",
  "grant_type": "authorization_code"
}
```

### Response
#### Success Response (200 OK)
- **access_token** (string) - The access token for making API calls.
- **token_type** (string) - The type of token, usually `Bearer`.
- **id_token** (string) - A signed JWT containing user identity claims.

#### Response Example
```json
{
  "access_token": "idntk.abc123...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Error Response
- **400 Bad Request** - If the authorization code is invalid or expired.
```

--------------------------------

### JWKS Endpoint

Source: https://auth.hackclub.com/docs/oidc-guide

Fetch the JSON Web Key Set (JWKS) which contains the public keys used to verify the signature of ID tokens.

```APIDOC
## GET /oauth/discovery/keys

### Description
Retrieves the JSON Web Key Set (JWKS) used for verifying the signature of ID tokens.

### Method
GET

### Endpoint
`/oauth/discovery/keys`

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200 OK)
- **keys** (array) - An array of public keys in JWK format.
```

--------------------------------

### Hack Club OIDC Discovery URL

Source: https://auth.hackclub.com/docs/oidc-guide

The OpenID Connect discovery URL for Hack Club Auth. This URL provides metadata about the authentication server, which OIDC client libraries use to configure themselves.

```plaintext
https://auth.hackclub.com/.well-known/openid-configuration
```

--------------------------------

### OIDC Reauthentication with max_age

Source: https://auth.hackclub.com/docs/oidc-guide

Require user re-authentication if their current session is older than a specified number of seconds by using the `max_age` parameter in the authorization request.

```HTTP
max_age=3600
```

--------------------------------

### OIDC Authorization Request

Source: https://auth.hackclub.com/docs/oidc-guide

Redirect users to the Hack Club Auth authorization endpoint to initiate the login process. This request includes your client ID, redirect URI, response type, and requested scopes.

```HTTP
GET https://auth.hackclub.com/oauth/authorize?client_id=your_client_id&redirect_uri=https%3A%2F%2Farcade.hackclub.com%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email
```

--------------------------------

### OIDC Token Exchange Request

Source: https://auth.hackclub.com/docs/oidc-guide

Exchange the authorization code received after user consent for access and ID tokens. This POST request requires your client ID, client secret, redirect URI, the authorization code, and grant type.

```HTTP
POST https://auth.hackclub.com/oauth/token

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://arcade.hackclub.com/auth/callback",
  "code": "a1b2c3d4e5f6",
  "grant_type": "authorization_code"
}
```

--------------------------------

### OIDC JWKS Endpoint

Source: https://auth.hackclub.com/docs/oidc-guide

Fetch the JSON Web Key Set (JWKS) from this endpoint to obtain the public keys used to verify the signature of the ID token. This is crucial for validating the integrity of the token.

```HTTP
GET /oauth/discovery/keys
```

--------------------------------

### Retrieve Authenticated User Identity

Source: https://auth.hackclub.com/docs/api

Fetches the identity information of the currently authenticated user based on granted OAuth scopes. Returns a JSON object containing user details and active scopes.

```JSON
{
  "identity": {
    "id": "ident!Gjfr0w",
    "first_name": "Heidi",
    "last_name": "Trashworth",
    "primary_email": "heidi897@hackclub.com"
  },
  "scopes": ["email", "name", "verification_status"]
}
```

--------------------------------

### OIDC Token Exchange Response

Source: https://auth.hackclub.com/docs/oidc-guide

The response from the token exchange endpoint contains the access token, token type, and the ID token. The ID token is a signed JWT with user identity claims.

```JSON
{
  "access_token": "idntk.abc123...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.