# API keys

The keys of your organization. Read only; create, roll and revoke keys in HQ.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List API keys [#list-api-keys]

    <ApiEndpointHeader method="GET" path="/v1/api_keys" scope="api_keys:read" />

    Every key of the organization, newest first. Metadata only, never a secret.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="status" type="string">
        Only active or only revoked keys. One of `active`, `revoked`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [ApiKey](#apikey) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of keys.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/api_keys \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/api_keys",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "api_key",
          "id": "key_ff7QejQ24AGmu5tv2IXIdw",
          "name": "CI deploy bot",
          "kind": "service_key",
          "prefix": "hq_live_acme_7Gm2",
          "last4": "Lk2Q",
          "acting_user": null,
          "role": "sys:member",
          "scopes": ["teams:read", "sessions:read"],
          "team_scope": "all",
          "teams": null,
          "ip_allowlist": ["203.0.113.0/24"],
          "api_version": "2026-11-01",
          "status": "active",
          "created_at": "2026-10-01T09:12:44.000Z",
          "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q",
          "expires_at": "2027-10-01T09:12:44.000Z",
          "last_used_at": "2026-10-14T16:02:11.000Z",
          "last_used_ip": "203.0.113.24",
          "revoked_at": null,
          "revoked_reason": null,
          "rotated_from": null,
          "rotation_grace_until": null
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Revoke the calling key [#revoke-the-calling-key]

    <ApiEndpointHeader method="DELETE" path="/v1/api_keys/current" access="key" />

    The key making this request revokes itself, at once. Use it the moment a key leaks. Any key
    may call it; nothing else about keys can be changed through the API.

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Revoked. The next request with this key gets 401.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys/current', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/api_keys/current",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Revoked. The next request with this key gets 401.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an API key [#get-an-api-key]

    <ApiEndpointHeader method="GET" path="/v1/api_keys/{key_id}" scope="api_keys:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="key_id" type="string" required="true">
        An API key id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [ApiKey](#apikey) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The key.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "api_key",
      "id": "key_ff7QejQ24AGmu5tv2IXIdw",
      "name": "CI deploy bot",
      "kind": "service_key",
      "prefix": "hq_live_acme_7Gm2",
      "last4": "Lk2Q",
      "acting_user": null,
      "role": "sys:member",
      "scopes": ["teams:read", "sessions:read"],
      "team_scope": "all",
      "teams": null,
      "ip_allowlist": ["203.0.113.0/24"],
      "api_version": "2026-11-01",
      "status": "active",
      "created_at": "2026-10-01T09:12:44.000Z",
      "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "expires_at": "2027-10-01T09:12:44.000Z",
      "last_used_at": "2026-10-14T16:02:11.000Z",
      "last_used_ip": "203.0.113.24",
      "revoked_at": null,
      "revoked_reason": null,
      "rotated_from": null,
      "rotation_grace_until": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### ApiKey [#apikey]

    An API key. Never carries the key itself.

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="kind" type="string">
        Open-ended; more credential kinds may be added.
      </ApiParam>

      <ApiParam name="prefix" type="string">
        The first characters of the key, for recognising it.
      </ApiParam>

      <ApiParam name="last4" type="string" />

      <ApiParam name="acting_user" type="string or null" />

      <ApiParam name="role" type="string or null" />

      <ApiParam name="scopes" type="array of string" />

      <ApiParam name="team_scope" type="string">
        One of `all`, `selected`.
      </ApiParam>

      <ApiParam name="teams" type="array of string or null" />

      <ApiParam name="ip_allowlist" type="array of string or null">
        Null when the key has none, and always null unless the caller is an owner or admin key for all teams.
      </ApiParam>

      <ApiParam name="api_version" type="string (date)" />

      <ApiParam name="status" type="string">
        Open-ended: active, expiring_rotation, revoked, expired.
      </ApiParam>

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="created_by" type="string or null" />

      <ApiParam name="expires_at" type="string (date-time)" />

      <ApiParam name="last_used_at" type="string or null" />

      <ApiParam name="last_used_ip" type="string or null">
        Always null unless the caller is an owner or admin key for all teams.
      </ApiParam>

      <ApiParam name="revoked_at" type="string or null" />

      <ApiParam name="revoked_reason" type="string or null" />

      <ApiParam name="rotated_from" type="string or null" />

      <ApiParam name="rotation_grace_until" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The ApiKey object"
    {
      "object": "api_key",
      "id": "key_ff7QejQ24AGmu5tv2IXIdw",
      "name": "CI deploy bot",
      "kind": "service_key",
      "prefix": "hq_live_acme_7Gm2",
      "last4": "Lk2Q",
      "acting_user": null,
      "role": "sys:member",
      "scopes": ["teams:read", "sessions:read"],
      "team_scope": "all",
      "teams": null,
      "ip_allowlist": ["203.0.113.0/24"],
      "api_version": "2026-11-01",
      "status": "active",
      "created_at": "2026-10-01T09:12:44.000Z",
      "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q",
      "expires_at": "2027-10-01T09:12:44.000Z",
      "last_used_at": "2026-10-14T16:02:11.000Z",
      "last_used_ip": "203.0.113.24",
      "revoked_at": null,
      "revoked_reason": null,
      "rotated_from": null,
      "rotation_grace_until": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
