HourSquare OAuth API

openapi: 3.2.0
info:
  title: HourSquare Public OAuth API
  description: 'The HourSquare public API: record clock events and completed shifts, read time entries, and list employees for one company.


    **Authentication.** Create an API key in HourSquare (Settings → API & integrations; you see it once). Exchange it for an access token at `https://api.hoursquare.com/api/public/v1/oauth/token` (OAuth 2.0 client credentials: `grant_type=client_credentials`, the key as `client_secret` or as the HTTP Basic password). Send the token as `Authorization: Bearer `. **Tokens live 15 minutes** — cache one and request a new one when it expires or on a 401. Never put a key or a token in a URL.


    **Scopes.** A key carries the scopes it was created with; each operation below names the one it needs (`attendance.record`, `attendance.read`, `employees.read`, …). A person''s own HourSquare token may also call the operations their permissions cover. Calling without the scope returns `403 insufficient_scope`. When fetched with a token, this document lists only the operations that token may call.


    **Rate limits.** 300 requests per minute per key on these resources and 60 per minute per key on the token endpoint, sliding windows, enforced per server instance (so approximately). Every response carries `RateLimit`, `RateLimit-Policy` and `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`; a `429 rate_limited` carries `Retry-After`.


    **Revocation.** Revoking a key stops new tokens immediately; tokens already issued keep working until they expire, so **within 15 minutes of Revoke every request with that key fails**.


    **Errors.** Every error is `application/problem+json` (RFC 9457) with a stable snake_case `error` you can branch on (`employee_not_found`, `already_clocked_in`, `no_open_session`, `session_too_long`, `overlaps_existing_entry`, `day_locked`, `validation_failed`, `idempotency_key_reused`, `time_tracking_disabled`, `insufficient_scope`, `rate_limited`, …), the numeric `code`, a human `detail`, and a `correlationId` to quote to support. `validation_failed` (422) lists the offending fields in `errors[]`.


    **Idempotency.** Send an `Idempotency-Key` header (unique per request, at most 128 characters) on writes to make retries safe: the same key replays the first response. Without it, the same employee, event type and caller within 60 seconds of an existing entry returns that entry with `200` instead of a duplicate; a later retry may see `409` instead of the original `201`.


    **Dry run.** `X-HourSquare-Dry-Run: true` on any write validates and resolves everything, writes nothing, and returns the would-be result with `dryRun: true` and status 200. This document declares the header with default `true`, so a try-it panel never writes unless you flip it; the server treats an absent header as a real write.


    **Time zones.** `occurredAt`, `clockIn` and `clockOut` are RFC 3339 timestamps with an explicit offset. They are recorded in the employee''s workplace time zone, else the company''s; when neither is configured the wall-clock you sent is kept. The response echoes `timeZone` (an IANA id or `offset`) and the server-resolved instant.


    **Versioning.** The major version is in the path (`/api/public/v1`). Within v1 only additive changes happen: new optional fields, new endpoints, new enum values (documented as "may grow"). Breaking changes get `/v2`; v1 then carries `Deprecation` and `Sunset` headers for at least six months.


    **Keep it safe.** Keys and tokens never belong in a URL, a browser page or a log; rotate a key when in doubt (the old one keeps working for the grace period you choose).'
  version: v1
servers:
- url: https://api.hoursquare.com
  description: HourSquare public API
tags:
- name: OAuth
  description: Turning an API key into a short-lived access token.
paths:
  /api/public/v1/oauth/token:
    post:
      tags:
      - OAuth
      summary: Exchange an API key for an access token
      description: 'OAuth 2.0 client credentials (RFC 6749 §4.4). Send `grant_type=client_credentials` as `application/x-www-form-urlencoded` and the key either as the `client_secret` field or as the HTTP Basic password (`Authorization: Basic base64(hsq_xxxxxxxx:)`). The token lives 15 minutes (`expires_in`, seconds): cache it and request a new one when it elapses or on a 401. This endpoint is served by the identity service under the same host; it allows 60 requests per minute per key. Every response is `Cache-Control: no-store`.'
      operationId: OAuth_Token
      requestBody:
        description: OAuth 2.0 client-credentials request (RFC 6749 §4.4.2).
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  description: Always `client_credentials`.
                  enum:
                  - client_credentials
                client_id:
                  type: string
                  description: Optional. The key's public id, with or without the `hsq_` prefix. When present it must match the key.
                client_secret:
                  type: string
                  description: The whole key (`hsq_…`). Omit it when the key travels as the HTTP Basic password instead. Never send it in the query string.
        required: true
      responses:
        '200':
          description: The access token. `token_type` is always `Bearer`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '400':
          description: '`invalid_request` (unreadable body, a secret in the query string, two authentication mechanisms, a repeated parameter) or `unsupported_grant_type` (anything but `client_credentials`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '401':
          description: '`invalid_client`: unknown key, wrong secret, or a key that is revoked, expired, outside its IP allowlist, or whose company has API access switched off (`error_description` says which once possession is proved).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
components:
  schemas:
    OAuthErrorResponse:
      type: object
      description: RFC 6749 §5.2 error response (documentation-only type).
      additionalProperties: false
      properties:
        error:
          type: string
        error_description:
          type: string
    OAuthTokenResponse:
      type: object
      description: RFC 6749 §5.1 token response, as Identity's token endpoint returns it (documentation-only type).
      additionalProperties: false
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
          format: int32
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'Client credentials (RFC 6749 §4.4): POST your API key as `client_secret` (or as the HTTP Basic password) to the token URL and use the returned token as a Bearer. Tokens live 15 minutes. Each operation lists the scope it requires; a key carries the scopes it was created with.'
      flows:
        clientCredentials:
          tokenUrl: https://api.hoursquare.com/api/public/v1/oauth/token
          scopes:
            attendance.record: Record clock events and completed shifts; set employee external ids (permission 86)
            attendance.read: Read time entries (permission 47)
            attendance.reports: Read time reports (permission 49)
            employees.read: Read employees (id, external id, name, email, status) (permission 52)
            leave.read: Read leave balances and requests (permission 72)
    BearerToken:
      type: http
      description: 'An access token from the token endpoint (`Authorization: Bearer <access_token>`), or a person''s own HourSquare session token: a person may call the read operations their permissions cover.'
      scheme: bearer
      bearerFormat: JWT
x-generator: NSwag v14.0.0.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))