> ## 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.

# Check authorization status

> Polls the status of a previously-created authorization request. Returns
`202 Accepted` while the request is pending, and `200 OK` once it is
completed, expired, or failed.

On the first response with `status = completed`, the request is marked as
consumed; subsequent calls return `403 Forbidden`. Requests older than 15
minutes are automatically transitioned to `expired`.


* Checks the current status of an authorization request
* Returns completion details if the user has completed the authorization flow
* Requires Bearer token authentication with your program API key
* Poll this endpoint every 2-3 seconds until status becomes `completed`


## OpenAPI

````yaml GET /api/authorize/{auth_id}/status
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/{auth_id}/status:
    get:
      tags:
        - Authorization
      summary: Check authorization status
      description: >-
        Checks the current status of an authorization request. Returns
        completion details if the user has completed the authorization flow.
      parameters:
        - name: auth_id
          in: path
          required: true
          description: The authorization request ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Authorization status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthStatusResponse'
              examples:
                pending:
                  summary: Authorization still pending
                  value:
                    auth_id: 8eaa8b02-1018-4075-aec0-7872e5db18aa
                    status: pending
                    created_at: '2025-08-27T00:11:18.546Z'
                    verified: false
                    identity_response: null
                completed:
                  summary: Authorization completed
                  value:
                    auth_id: 8eaa8b02-1018-4075-aec0-7872e5db18aa
                    status: completed
                    created_at: '2025-08-27T00:11:18.546Z'
                    idv_rec: user123
                    completed_at: '2025-08-27T00:15:30.123Z'
                    verified: true
                    identity_response:
                      id: id_123
                      verification_status: verified
                      ysws_eligible: true
                      email: user@example.com
                expired:
                  summary: Authorization expired
                  value:
                    auth_id: 8eaa8b02-1018-4075-aec0-7872e5db18aa
                    status: expired
                    created_at: '2025-08-27T00:11:18.546Z'
                    verified: false
                    error: Authorization expired
                    identity_response: null
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
              example:
                error: Invalid or inactive API key
        '404':
          description: Authorization request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
              example:
                error: Authorization request not found
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AuthStatusResponse:
      type: object
      required:
        - auth_id
        - status
        - created_at
      properties:
        auth_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - completed
            - expired
            - failed
          description: Current status of the authorization request
        created_at:
          type: string
          format: date-time
        idv_rec:
          type: string
          description: Identity record ID (only present when status is 'completed')
        completed_at:
          type: string
          format: date-time
          description: >-
            When the authorization was completed (only present when status is
            'completed')
        verified:
          type: boolean
          description: >-
            Whether the identity is verified and eligible. Present for all
            statuses to mirror /api/verify (true for completed, false
            otherwise).
        identity_response:
          description: >-
            Filtered identity fields, mirroring /api/verify. Present when
            completed; null otherwise.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/IdentityResponse'
        error:
          type: string
          description: Present for non-success statuses (e.g., expired or failed).
    AuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    IdentityResponse:
      type: object
      description: >-
        Normalized identity data. Fields may vary based on program scopes. The
        minimal default set includes: id, verification_status, ysws_eligible,
        email. Additional fields like slack_id can be requested via program
        scopes.
      properties:
        id:
          type: string
          description: Identity ID
        verification_status:
          type: string
          description: Verification status of the identity
          enum:
            - verified
            - pending
            - rejected
            - unverified
        ysws_eligible:
          type: boolean
          description: Whether the identity is eligible for YSWS programs (18 and under).
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        slack_id:
          type: string
          description: >-
            Slack user ID (available when slack_id scope is enabled for the
            program)
        rejection_reason:
          type: string
      additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Program API key obtained from the admin dashboard

````