HourSquare Me API

openapi: 3.2.0
info:
  title: HourSquare Public Me 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: Me
paths:
  /api/public/v1/me:
    get:
      tags:
      - Me
      summary: Describe the current token
      description: 'Works with any valid token, key or person: which kind of principal it is, its id (and the key''s

        `hsq_` public id), the company it belongs to, the scopes it may use, when it expires, and the quota

        it is charged against (`requestsPerMinute`, per pod — so "approximately"). No scope required.'
      operationId: Me_Get
      responses:
        '200':
          description: The token, described.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          description: The bearer token is missing, invalid or expired (`invalid_token`). Request a new token from the token endpoint.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: The token is not allowed here (`forbidden`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: 'Rate limit exceeded (`rate_limited`): 300 requests per minute per key on this surface, approximately (per pod). Honour `Retry-After` and the `RateLimit` headers.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - OAuth2: []
      - BearerToken: []
components:
  schemas:
    ProblemDetails:
      type: object
      description: "The wire shape. Code is the numeric ApiExceptionCodeTypes value,\n            Error the stable snake_case string integrators branch on."
      additionalProperties: false
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        code:
          type: integer
          format: int32
        error:
          type: string
        correlationId:
          type:
          - string
          - 'null'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ProblemFieldError'
    MeScope:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        permission:
          type: integer
          format: int32
        label:
          type: string
    MeResponse:
      type: object
      additionalProperties: false
      properties:
        principal:
          type: string
        id:
          type: string
          format: guid
        publicId:
          type:
          - string
          - 'null'
        companyId:
          type: string
          format: guid
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/MeScope'
        tokenExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
        rateLimit:
          $ref: '#/components/schemas/MeRateLimit'
        dryRunHeader:
          type: string
    ProblemFieldError:
      type: object
      description: One validation failure inside Errors.
      additionalProperties: false
      properties:
        field:
          type: string
        message:
          type: string
        code:
          type:
          - string
          - 'null'
    MeRateLimit:
      type: object
      additionalProperties: false
      properties:
        requestsPerMinute:
          type: integer
          format: int32
        tokenRequestsPerMinute:
          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))