> ## Documentation Index
> Fetch the complete documentation index at: https://docs.identity.hackclub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create authorization request

> Creates a new authorization request scoped to the program identified by the
bearer API key. Returns a popup URL the end user must open to complete
identity authorization. Requests expire after 15 minutes.


* Creates a new authorization request for headless OAuth flows
* Returns a popup URL that users can visit to complete identity verification
* Requires Bearer token authentication with your program API key
* Authorization requests expire after 15 minutes


## OpenAPI

````yaml POST /api/authorize
openapi: 3.1.0
info:
  title: Hack Club Submit API
  description: >-
    API for identity verification and headless authorization flows. Includes
    endpoints for verifying user identities and programmatic authorization via
    popup flows.
  license:
    name: MIT
  version: 1.1.0
servers:
  - url: https://submit.hackclub.com
security: []
paths:
  /api/authorize:
    post:
      tags:
        - Authorization
      summary: Create authorization request
      description: >-
        Creates a new authorization request for headless OAuth flows. Returns a
        popup URL that users can visit to complete identity verification.
      responses:
        '200':
          description: Authorization request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
              example:
                auth_id: 8eaa8b02-1018-4075-aec0-7872e5db18aa
                popup_url: >-
                  https://submit.hackclub.com/popup/authorize/8eaa8b02-1018-4075-aec0-7872e5db18aa
                status: pending
                expires_at: '2025-08-27T00:26:18.573Z'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
              example:
                error: Invalid or inactive API key
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AuthorizeResponse:
      type: object
      required:
        - auth_id
        - popup_url
        - status
        - expires_at
      properties:
        auth_id:
          type: string
          format: uuid
          description: Unique identifier for this authorization request
        popup_url:
          type: string
          format: uri
          description: >-
            URL for the user to visit in a popup window to complete
            authorization
        status:
          type: string
          enum:
            - pending
          description: Current status of the authorization request
        expires_at:
          type: string
          format: date-time
          description: When this authorization request expires (15 minutes from creation)
    AuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Program API key obtained from the admin dashboard

````