### OAuth Authorization

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

Construct the authorization URL to redirect users to Hack Club for authentication and app approval.

```APIDOC
## GET /oauth/authorize

### Description
Redirect users to this endpoint to initiate the OAuth 2.0 authorization flow. Users will be prompted to log in to their Hack Club Account and grant your application permission to access their data based on the requested scopes.

### Method
GET

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

### Query Parameters
- **client_id** (string) - Required - Your application's unique Client ID.
- **redirect_uri** (string) - Required - The URI Hack Club will redirect the user to after authorization. Must be one of the URIs configured for your OAuth application.
- **response_type** (string) - Required - Must be set to `code`.
- **scope** (string) - Optional - A space-separated list of requested scopes. Available scopes include `email`, `name`, `slack_id`, `verification_status`, and potentially others for HQ official applications.

### Request Example
`GET https://account.hackclub.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code&scope=email%20name`
```

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

### Token Exchange

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

Exchange the authorization code received after user approval for an access token.

```APIDOC
## POST /oauth/token

### Description
Exchange the authorization `code` obtained from the `/oauth/authorize` endpoint for an `access_token`. This is a server-to-server request.

### Method
POST

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

### Request Body
- **client_id** (string) - Required - Your application's Client ID.
- **client_secret** (string) - Required - Your application's Client Secret. Store this securely and do not expose it in client-side code.
- **redirect_uri** (string) - Required - The same redirect URI used in the authorization request.
- **code** (string) - Required - The authorization code received in the callback.
- **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://yourapp.com/callback",
  "code": "AUTHORIZATION_CODE_FROM_CALLBACK",
  "grant_type": "authorization_code"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The token used to authenticate API requests.
```

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

### GET /api/v1/me

Source: https://account.hackclub.com/docs/tldr

Retrieves the authenticated user's profile information using a bearer token obtained from the OAuth flow.

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

### Description
This endpoint allows you to fetch the profile details of the currently authenticated user. You must include a valid bearer token in the `Authorization` header, which is obtained after a successful OAuth 2.0 flow.

### Method
GET

### Endpoint
`/api/v1/me`

### Parameters
#### Query Parameters
None

#### Path Parameters
None

#### Request Body
None

### Request Example
```
GET /api/v1/me HTTP/1.1
Host: account.hackclub.com
Authorization: Bearer YOUR_ACCESS_TOKEN

```

### Response
#### Success Response (200 OK)
- **id** (integer) - The unique identifier for the user.
- **name** (string) - The user's full name.
- **email** (string) - The user's email address.
- **hackathon_clubs** (array) - List of hackathon clubs the user is associated with.
- **avatar_url** (string) - URL to the user's profile picture.

#### Response Example
```json
{
  "id": 12345,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "hackathon_clubs": ["Apollo", "Orbit"],
  "avatar_url": "https://example.com/avatars/jane.doe.png"
}
```
```

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

### Construct Authorization URL for Hack Club OAuth

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

Build the authorization URL to redirect users to Hack Club Accounts for authentication. Include your client ID, redirect URI, response type, and requested scopes. The `scope` parameter defines the user information your application can access.

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

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

### API Error Response Example

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

Standard error response format for API endpoints. Includes an 'error' field for a general error type and a 'message' field for more specific details. Common HTTP status codes are 401, 403, 404, and 422.

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

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

### Authenticated API Request

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

Include the obtained access token in the Authorization header to make authenticated requests to the Hack Club Account API.

```APIDOC
## Authenticated API Requests

### Description
To access protected resources on the Hack Club Account API, include the `access_token` obtained from the token exchange step in the `Authorization` header of your HTTP requests.

### Method
Any (e.g., GET, POST, PUT, DELETE)

### Endpoint
Any Hack Club Account API endpoint (e.g., `/api/v1/me`)

### Headers
- **Authorization** (string) - Required - Must be formatted as `Bearer YOUR_ACCESS_TOKEN`.

### Request Example (GET /api/v1/me)
```http
GET /api/v1/me HTTP/1.1
Host: account.hackclub.com
Authorization: Bearer YOUR_ACCESS_TOKEN
```
```

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

### Get Authenticated User's Identity (GET /api/v1/me)

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

Retrieves the authenticated user's identity information, including ID, name, email, and address details, based on the granted OAuth scopes. Requires an 'Authorization: Bearer <token>' header.

```json
{
  "identity": {
    "id": "ident!ZXkfXB",
    "ysws_eligible": true,
    "verification_status": "needs_submission",
    "first_name": "Heidi",
    "last_name": "Trashworth",
    "primary_email": "heidi61@hackclub.com",
    "slack_id": "U00000061",
    "phone_number": "+18028675309",
    "birthday": "2005-06-15",
    "legal_first_name": "Hakkuun",
    "legal_last_name": "[WOULDN\'T YOU LIKE TO KNOW]",
    "addresses": [
      {
        "id": "addr!jmruXK",
        "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",
        "primary": true
      }
    ]
  },
  "scopes": [
    "email",
    "name",
    "verification_status",
    "slack_id",
    "basic_info",
    "address",
    "legal_name"
  ]
}
```

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

### Get Specific User Identity by ID (GET /api/v1/identities/:id)

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

Retrieves a specific user's identity information using their public ID. This endpoint requires authentication with a program key and is intended for HQ official programs. The returned fields depend on the program's configured scopes.

```json
{
  "identity": {
    "id": "ident!D5mfan",
    "first_name": "Heidi",
    "last_name": "Hacksworth"
  }
}
```

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

### Exchange Authorization Code for Access Token (POST Request)

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

Send a POST request to the Hack Club OAuth token endpoint to exchange the authorization code received after user consent for an access token. This request requires your client ID, client secret, redirect URI, the authorization code, and the grant type.

```javascript
POST https://account.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"
}
```

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

### GET /api/external/check

Source: https://account.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

### Parameters
#### Path Parameters
None

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

#### Request Body
None

### Request Example
`GET /api/external/check?email=orpheus@hackclub.com`

### Response
#### Success Response (200)
- **result** (string) - The verification result.

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

**Possible result values:**
- `needs_submission` - User hasn't started verification
- `pending` - Verification is being reviewed
- `verified_eligible` - Verified and eligible for YSWS (under 18)
- `verified_but_over_18` - Verified but over 18
- `rejected` - Verification was rejected
- `not_found` - No user found with the provided identifier
```

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

### Include Access Token in API Request Header

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

Authenticate requests to the Hack Club Account API by including the obtained access token in the `Authorization` header. The token should be prefixed with `Bearer `.

```http
Authorization: Bearer idntk.mraowj2z72e1x8i2a60o88j3h7d0f1
```

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

### GET /api/v1/me

Source: https://account.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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **identity** (object) - The user's identity information.
  - **id** (string) - User's unique identifier.
  - **ysws_eligible** (boolean) - Whether the user is eligible for YSWS.
  - **verification_status** (string) - The current verification status.
  - **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 (YYYY-MM-DD).
  - **legal_first_name** (string) - User's legal first name.
  - **legal_last_name** (string) - User's legal last name.
  - **addresses** (array) - User's mailing addresses.
- **scopes** (array) - List of granted scopes.

#### Response Example
```json
{
  "identity": {
    "id": "ident!ZXkfXB",
    "ysws_eligible": true,
    "verification_status": "needs_submission",
    "first_name": "Heidi",
    "last_name": "Trashworth",
    "primary_email": "heidi61@hackclub.com",
    "slack_id": "U00000061",
    "phone_number": "+18028675309",
    "birthday": "2005-06-15",
    "legal_first_name": "Hakkuun",
    "legal_last_name": "[WOULDN'T YOU LIKE TO KNOW]",
    "addresses": [
      {
        "id": "addr!jmruXK",
        "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",
        "primary": true
      }
    ]
  },
  "scopes": [
    "email",
    "name",
    "verification_status",
    "slack_id",
    "basic_info",
    "address",
    "legal_name"
  ]
}
```

**Verification status values:**
- `needs_submission` - User hasn't started verification
- `pending` - Verification is being reviewed
- `verified` - Successfully verified
- `ineligible` - Verification was rejected
```

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

### API Authentication with Bearer Token

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

Most API endpoints require an OAuth access token for authentication. This token should be included in the 'Authorization' header as a Bearer token. Program keys, starting with 'prgmk.', can also be used for machine-to-machine calls.

```http
Authorization: Bearer idntk.mraowj2z72e1x8i2a60o88j3h7d0f1
```

```http
Authorization: Bearer prgmk.abc123def456...
```

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

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

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

Retrieves a specific user's identity by their public ID. This endpoint requires a program key for authentication.

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

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

### Method
GET

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

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

#### Query Parameters
None

#### Request Body
None

### Request Example
`GET /api/v1/identities/ident!abc123`

### Response
#### Success Response (200)
- **identity** (object) - The user's identity information. Fields returned depend on your program's configured scopes.
  - **id** (string) - User's public ID.
  - **first_name** (string) - User's first name.
  - **last_name** (string) - User's last name.

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

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

### Check User Verification Status (GET /api/external/check)

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

Checks the verification status of a user using their ID, email, or Slack ID. This is a public endpoint and does not require authentication. It returns the verification result and eligibility.

```json
{
  "result": "verified_eligible"
}
```

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

### Hack Club OAuth Authentication

Source: https://account.hackclub.com/docs/tldr

This section details the process of authenticating users with Hack Club using OAuth 2.0, including authorization and token exchange.

```APIDOC
## Hack Club OAuth Authentication Flow

### Description
This process allows users to sign in to your application using their Hack Club account. It involves redirecting users to Hack Club's authorization server, obtaining an authorization code, and then exchanging this code for an access token.

### Method
GET (for authorization)
POST (for token exchange)

### Endpoint
**Authorization:** `https://account.hackclub.com/oauth/authorize`
**Token Exchange:** `POST /oauth/token`

### Parameters
#### Query Parameters for Authorization (`/oauth/authorize`)
- **client_id** (string) - Required - Your application's client ID.
- **redirect_uri** (string) - Required - The URI where Hack Club will redirect the user after authorization.
- **scope** (string) - Optional - The requested permissions (e.g., `read:profile`).
- **response_type** (string) - Required - Must be `code` for authorization code flow.

#### Request Body for Token Exchange (`POST /oauth/token`)
- **grant_type** (string) - Required - Must be `authorization_code`.
- **code** (string) - Required - The authorization code received from the redirect.
- **redirect_uri** (string) - Required - The same redirect URI used in the authorization request.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
**Authorization Request (Conceptual URL):**
```
https://account.hackclub.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=read:profile&response_type=code
```

**Token Exchange Request Body:**
```json
{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE_FROM_REDIRECT",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Response
#### Success Response (Token Exchange - 200 OK)
- **access_token** (string) - The access token for authenticating API requests.
- **token_type** (string) - The type of token (e.g., `Bearer`).
- **expires_in** (integer) - The number of seconds until the token expires.
- **refresh_token** (string) - A token to obtain new access tokens.
- **scope** (string) - The scopes granted.

#### Response Example (Token Exchange)
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "read:profile"
}
```
```

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

### List Identities

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

Retrieves a list of all identities that have authorized your application.

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

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

### Method
GET

### Endpoint
/api/v1/identities

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### 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!RnMfJ2",
      "first_name": "Heidi",
      "last_name": "Latta"
    },
    {
      "id": "ident!R9zf88",
      "first_name": "Heidi",
      "last_name": "Wofford"
    }
  ]
}
```

**Authentication:** Program key required
```

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

### Hack Club Account API Base URL

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

The base URL for all Hack Club Account API requests. All endpoint paths should be appended to this URL.

```url
https://account.hackclub.com
```

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

### List Identities (API)

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

This endpoint retrieves all identities authorized by your application. It requires a program key for authentication. The response is a JSON object containing a list of identity objects, each with an ID, first name, and last name.

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

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

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