# Secrets

Secret names and where they apply. A secret value is never returned.



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

<ApiEndpoint>
  <ApiEndpointMain>
    ## List an AI team's secrets [#list-an-ai-teams-secrets]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/secrets" scope="secrets.team:read" />

    Names, scope and teams. A value is never returned.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <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>
    </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 [Secret](#secret) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of secrets.
      </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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets \
          -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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets', {
          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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets",
            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": "secret",
          "id": "sec_vbGigyDOkNeK3aNzDuiclU",
          "name": "GITHUB_TOKEN",
          "scope": "org",
          "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
          "created_at": "2026-09-02T10:11:12.000Z",
          "updated_at": "2026-10-01T08:30:00.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an AI team's secret [#create-an-ai-teams-secret]

    <ApiEndpointHeader method="POST" path="/v1/teams/{team_id}/secrets" scope="secrets.team:write" />

    The value is write-only: no response carries it, and there is no reveal route on the API.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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="Body parameters">
      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The secret (never its value).
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"STRIPE_API_KEY","value":"your-stripe-key"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'STRIPE_API_KEY', value: 'your-stripe-key' }),
        });
        console.log(await res.json());
        ```
      </Tab>

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

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "STRIPE_API_KEY", "value": "your-stripe-key"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an AI team's secret [#get-an-ai-teams-secret]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/secrets/{secret_id}" scope="secrets.team:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="secret_id" type="string" required="true">
        A secret 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 [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The secret, without its value.
      </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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU \
          -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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU', {
          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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete an AI team's secret [#delete-an-ai-teams-secret]

    <ApiEndpointHeader method="DELETE" path="/v1/teams/{team_id}/secrets/{secret_id}" scope="secrets.team:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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">
        Done.
      </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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

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

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

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List organization secrets [#list-organization-secrets]

    <ApiEndpointHeader method="GET" path="/v1/secrets" scope="secrets.org:read" />

    Names, scope and teams. A value is never returned.

    <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>
    </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 [Secret](#secret) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of secrets.
      </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/secrets \
          -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/secrets', {
          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/secrets",
            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": "secret",
          "id": "sec_vbGigyDOkNeK3aNzDuiclU",
          "name": "GITHUB_TOKEN",
          "scope": "org",
          "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
          "created_at": "2026-09-02T10:11:12.000Z",
          "updated_at": "2026-10-01T08:30:00.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an org secret [#create-an-org-secret]

    <ApiEndpointHeader method="POST" path="/v1/secrets" scope="secrets.org:write" />

    Org-wide (`scope: org`) or shared with chosen teams (`scope: selected`).
    The value is write-only: no response carries it, and there is no reveal route on the API.
    A key restricted to some AI teams creates only `selected` secrets, for teams inside its
    restriction (an org-wide one is 403 team_restricted, another team 404).

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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="Body parameters">
      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="value" type="string" required="true" />

      <ApiParam name="scope" type="string">
        One of `org`, `selected`.
      </ApiParam>

      <ApiParam name="teams" type="array of string">
        With `scope: selected` only.
      </ApiParam>
    </ApiParams>

    **Returns** a [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The secret (never its value).
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/secrets \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"GITHUB_TOKEN","value":"your-github-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'GITHUB_TOKEN', value: 'your-github-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

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

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/secrets",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "GITHUB_TOKEN", "value": "your-github-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an organization secret [#get-an-organization-secret]

    <ApiEndpointHeader method="GET" path="/v1/secrets/{secret_id}" scope="secrets.org:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret 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 [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The secret, without its value.
      </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/secrets/sec_vbGigyDOkNeK3aNzDuiclU \
          -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/secrets/sec_vbGigyDOkNeK3aNzDuiclU', {
          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/secrets/sec_vbGigyDOkNeK3aNzDuiclU",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete an org secret [#delete-an-org-secret]

    <ApiEndpointHeader method="DELETE" path="/v1/secrets/{secret_id}" scope="secrets.org:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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">
        Done.
      </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/secrets/sec_vbGigyDOkNeK3aNzDuiclU \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

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

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

        import requests

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

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Replace an org secret's value [#replace-an-org-secrets-value]

    <ApiEndpointHeader method="PUT" path="/v1/secrets/{secret_id}/value" scope="secrets.org:write" />

    The value is write-only: no response carries it, and there is no reveal route on the API.

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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="Body parameters">
      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The secret (never its value).
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PUT https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"value":"your-new-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value', {
          method: 'PUT',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ value: 'your-new-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

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

        import requests

        res = requests.put(
            "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"value": "your-new-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Set the teams a selected secret reaches [#set-the-teams-a-selected-secret-reaches]

    <ApiEndpointHeader method="PUT" path="/v1/secrets/{secret_id}/teams" scope="secrets.org:assign" />

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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="Body parameters">
      <ApiParam name="teams" type="array of string" required="true" />
    </ApiParams>

    **Returns** a [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The secret (never its value).
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PUT https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"teams":["team_3kQ9vX2mR8tLpZ4wYc1aBd"]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams', {
          method: 'PUT',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ teams: ['team_3kQ9vX2mR8tLpZ4wYc1aBd'] }),
        });
        console.log(await res.json());
        ```
      </Tab>

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

        import requests

        res = requests.put(
            "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"]},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Share a selected secret with one more team [#share-a-selected-secret-with-one-more-team]

    <ApiEndpointHeader method="POST" path="/v1/secrets/{secret_id}/teams/{team_id}" scope="secrets.org:assign" />

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>

      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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">
        Done.
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

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

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

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Stop sharing a selected secret with a team [#stop-sharing-a-selected-secret-with-a-team]

    <ApiEndpointHeader method="DELETE" path="/v1/secrets/{secret_id}/teams/{team_id}" scope="secrets.org:assign" />

    <ApiParams title="Path parameters">
      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>

      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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">
        Done.
      </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/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

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

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

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Replace an AI team's secret value [#replace-an-ai-teams-secret-value]

    <ApiEndpointHeader method="PUT" path="/v1/teams/{team_id}/secrets/{secret_id}/value" scope="secrets.team:write" />

    The value is write-only: no response carries it, and there is no reveal route on the API.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="secret_id" type="string" required="true">
        A secret id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <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="Body parameters">
      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Secret](#secret) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The secret (never its value).
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PUT https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"value":"your-new-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value', {
          method: 'PUT',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ value: 'your-new-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

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

        import requests

        res = requests.put(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"value": "your-new-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Secret [#secret]

    A secret's name and where it applies. Deliberately has no value field.

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

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

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

      <ApiParam name="scope" type="string">
        One of `org`, `team`.
      </ApiParam>

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

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

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

  <ApiEndpointSamples>
    ```json title="The Secret object"
    {
      "object": "secret",
      "id": "sec_vbGigyDOkNeK3aNzDuiclU",
      "name": "GITHUB_TOKEN",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:11:12.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
