Add masked API key lookup

Expose organization-scoped API key metadata without admitting plaintext or API key lifecycle into Terraform. Use the tagged SDK's paginated search and enforce exact-name identity in the provider, with focused unit and opt-in acceptance coverage.

Author: IlyaasK

.github/workflows/acceptance.yml

@@ -46,6 +46,9 @@ jobs:
             package: ./internal/datasources/app
             project_id_required: true
             app_fixture_required: true
+          - name: API key data source
+            package: ./internal/datasources/apikey
+            project_id_required: true
           - name: Deployment data source
             package: ./internal/datasources/deployment
             project_id_required: true

CHANGELOG.md

@@ -8,15 +8,14 @@ First public v1 release candidate:
 
 - Provider configuration for `api_key`, `base_url`, and `project_id`.
 - Durable `kernel_project`, `kernel_browser_pool`, and `kernel_extension` resources.
-- Lookup-only `kernel_app`, `kernel_browser_pool`, `kernel_deployment`, `kernel_project`, `kernel_profile`, `kernel_proxy`, and `kernel_extension` data sources.
+- Lookup-only `kernel_api_key`, `kernel_app`, `kernel_browser_pool`, `kernel_deployment`, `kernel_project`, `kernel_profile`, `kernel_proxy`, and `kernel_extension` data sources.
 - Stable import for every registered resource, including project-qualified browser-pool and extension forms.
 - Unit tests, generated Terraform docs, Terraform examples, CI checks, and an opt-in live acceptance matrix.
 
 Intentionally deferred from the first public v1 because their durable API, SDK, or sensitive-state contracts are incomplete:
 
 - Runtime browser/session operations such as acquire, release, flush, app invocation, screenshots, logs, live view, and force recovery.
 - API key, profile, proxy, and deployment resources.
-- API key data source.
 - `force_destroy` browser-pool deletion.
 - Terraform Plugin Framework code generation.
 

README.md

@@ -20,6 +20,7 @@ Resources:
 
 Data sources:
 
+- `kernel_api_key`
 - `kernel_app`
 - `kernel_browser_pool`
 - `kernel_deployment`

docs/acceptance.md

@@ -50,15 +50,15 @@ Actions secrets and must not be printed.
 | `kernel_proxy` data source | Test present | A uniquely created managed datacenter proxy is read by canonical ID and exact name through explicit and provider-default project scope; durable type/protocol metadata, no-drift planning, and post-cleanup coded `not_found` are verified without fixture credentials. | None. |
 | `kernel_app` data source | Test present | A release-owned running app version is read by exact name/version through explicit and provider-default project scope; canonical deployment metadata and no-drift planning are verified without invocation. Unit coverage verifies action-name and environment-key flattening without environment values. | Keep `KERNEL_ACC_APP_NAME` and `KERNEL_ACC_APP_VERSION` pointed at exactly one running app version in the acceptance project. |
 | `kernel_deployment` data source | Test present | The deployment backing the release-owned app fixture is read by canonical ID through explicit and provider-default project scope; direct GET metadata and no-drift planning are verified without logs or event streams. Unit coverage verifies that only environment variable names enter state. | Keep the release-owned app fixture running so its deployment ID remains readable. |
-| `kernel_api_key` data source | Deferred; unregistered | No provider surface yet. | Wait for a tagged SDK with exact-name filtering, then add masked ID/name lookup acceptance. |
+| `kernel_api_key` data source | Test present | A uniquely created project-scoped key is read by canonical ID and byte-exact name; masked metadata, no plaintext state, ambiguity behavior, no-drift planning, cleanup, and coded post-cleanup absence are covered. | Run with an organization-wide administrative `KERNEL_API_KEY`; project-scoped credentials cannot create or delete the fixture. |
 | Profile, proxy, deployment, and API-key resources | Deferred; unregistered | No provider surfaces yet. | Enter the matrix only after their documented API/SDK/state blockers are resolved and implementation lands. |
 
 "Test present" describes code in the repository; it does not claim a run
 against the release commit. The release record below supplies that evidence.
 
 ## Current Commands
 
-Run the ten existing packages independently for fast failure isolation:
+Run the eleven existing packages independently for fast failure isolation:
 
 ```sh
 go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc
@@ -69,6 +69,7 @@ go test -count=1 -timeout=30m -v ./internal/datasources/extension -run TestAcc
 go test -count=1 -timeout=30m -v ./internal/datasources/profile -run TestAcc
 go test -count=1 -timeout=30m -v ./internal/datasources/proxy -run TestAcc
 go test -count=1 -timeout=30m -v ./internal/datasources/app -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/datasources/apikey -run TestAcc
 go test -count=1 -timeout=30m -v ./internal/datasources/deployment -run TestAcc
 go test -count=1 -timeout=30m -v ./internal/datasources/browserpool -run TestAcc
 ```

docs/api-key-state.md

@@ -2,8 +2,9 @@
 
 ## Decision
 
-The masked `kernel_api_key` data source is safe to implement after a tagged
-Kernel Go SDK exposes the API's exact-name list filter.
+The masked `kernel_api_key` data source is supported. It uses the tagged Kernel
+Go SDK's paginated query filter, then enforces byte-exact name equality in the
+provider and diagnoses ambiguous names.
 
 The `kernel_api_key` resource is deferred. Its Terraform state shape is
 accepted below, but Create and Rotate must not ship until the API provides
@@ -51,9 +52,11 @@ has these properties:
 - A deleted key is hidden from ordinary Get and a repeated Delete returns
   `not_found`.
 
-The API supports an exact-name List filter. It is generated in the pending Go
-SDK v0.77.0 release, so the provider must wait for that tag rather than adding
-direct HTTP or a second client.
+The API supports substring query today and has a dedicated exact-name List
+filter pending in Go SDK v0.77.0. The data source does not require the pending
+filter: it scans every query page, post-filters names byte-for-byte, and
+deduplicates canonical IDs. The provider still uses only the tagged SDK and
+does not add direct HTTP or a second client.
 
 ## Future Resource State
 
@@ -180,9 +183,9 @@ replay contract.
 
 ## Masked Data Source
 
-The data source is independent of plaintext lifecycle and may ship first. It
-should accept exactly one of canonical `id` or exact `name`, scan all pages for
-name lookup, deduplicate by ID, and diagnose zero or multiple non-deleted
+The data source is independent of plaintext lifecycle. It accepts exactly one
+of canonical `id` or exact `name`, scans all pages for name lookup, deduplicates
+by ID, and diagnoses zero or multiple non-deleted
 matches. Expired-but-not-deleted keys remain visible because they are durable
 records under the current API status definition. The API's name filter follows
 the production database's case- and accent-insensitive collation; the provider
@@ -195,7 +198,6 @@ or provider-authentication identity.
 
 ## Unblocking Checklist
 
-- Tag an SDK release containing the exact API-key name filter.
 - Add replayable idempotency for API-key Create and Rotate.
 - Add a stable current-key/project-scope signal or coded self-rotation
   rejection plus effective-scope metadata.

docs/architecture.md

@@ -56,6 +56,7 @@ Core v1 resources:
 
 Core v1 data sources:
 
+- `kernel_api_key`
 - `kernel_project`
 - `kernel_browser_pool`
 - `kernel_profile`
@@ -67,17 +68,17 @@ Core v1 data sources:
 Late or conditional v1 work:
 
 - `kernel_proxy` resource, after write-only credential/import semantics are accepted and a tagged SDK exposes in-place rename
-- masked `kernel_api_key` metadata lookup
 - `kernel_api_key` resource, only after plaintext-once, retry, rotation, import, and provider self-use semantics are accepted
 - project limits, only after their lifecycle is clearly separate from basic project management
 
 Blocked candidates must remain unimplemented until the API and a tagged SDK expose the required durable contract. Provider code must not guess missing semantics, patch generated SDK code, or add a fallback HTTP client to bypass the durable client module.
 
 The accepted plaintext, import, rotation, and self-use model for API keys is
 defined in [API Key Terraform State Design](api-key-state.md). The masked data
-source may proceed after the exact-name SDK surface is tagged. The resource
-remains blocked on replayable Create/Rotate idempotency and a current-key
-rotation guard with effective authenticated project-scope metadata.
+source scans the tagged SDK's paginated query results and enforces byte-exact
+name equality in provider code. The resource remains blocked on replayable
+Create/Rotate idempotency and a current-key rotation guard with effective
+authenticated project-scope metadata.
 
 `kernel_deployment` remains core v1 scope but is currently blocked until a
 tagged SDK exposes source provenance, the API supports deterministic durable

docs/concerns.md

@@ -198,6 +198,20 @@ provenance until the tagged SDK returns those fields directly. The separate
 `kernel_app` remains a data source. It should perform exact app-name/version
 lookup and may expose environment variable keys, but never redacted values.
 
+### API Key Lookup And Resource Safety
+
+The tagged Go SDK exposes organization-scoped masked API-key Get and paginated
+List methods. List's `query` parameter is a case-insensitive substring search,
+not an exact-name filter. The `kernel_api_key` data source therefore scans all
+non-deleted result pages, deduplicates canonical IDs, and applies byte-exact name
+equality before accepting one match. It stores masked metadata only; plaintext
+creation and rotation values never enter the data-source schema or state.
+
+The API-key resource remains blocked. Create and Rotate return plaintext once
+but lack a replayable idempotency contract, and the provider cannot yet prove
+whether the managed key is the credential authenticating Terraform. Do not add
+resource lifecycle or rotation methods until those contracts are explicit.
+
 ### Browser Pool Selector Echoes
 
 Resolved upstream. Browser pool responses now include authoritative top-level

docs/data-sources/api_key.md

@@ -0,0 +1,32 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "kernel_api_key Data Source - Kernel"
+subcategory: ""
+description: |-
+  Lookup masked metadata for a non-deleted Kernel API key by canonical ID or exact name.
+---
+
+# kernel_api_key (Data Source)
+
+Lookup masked metadata for a non-deleted Kernel API key by canonical ID or exact name.
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `id` (String) Canonical API key ID.
+- `name` (String) API key name for exact lookup. Names are not unique, so ambiguous matches fail.
+
+### Read-Only
+
+- `created_at` (String) API key creation timestamp.
+- `created_by_email` (String) Email address of the key creator.
+- `created_by_id` (String) Kernel user ID of the key creator.
+- `created_by_name` (String) Display name of the key creator, when available.
+- `expires_at` (String) API key expiration timestamp, or null when the key does not expire.
+- `masked_key` (String, Sensitive) Masked API key metadata. Plaintext is never returned or stored.
+- `project_id` (String) Project ID for a project-scoped key, or null for an organization-wide key.
+- `project_name` (String) Project name for a project-scoped key, when available.

docs/migration-v1.md

@@ -64,9 +64,10 @@ path. Managing future content replacement requires Terraform 1.11 or later plus
 
 ## Newly Available Lookups
 
-V1 adds lookup-only app and browser-pool data sources alongside project,
-profile, proxy, and extension lookups. Data sources do not adopt or mutate the
-remote object. Exact lookup fails when no object or multiple objects match.
+V1 adds lookup-only API-key, app, browser-pool, and deployment data sources
+alongside project, profile, proxy, and extension lookups. Data sources do not
+adopt or mutate the remote object. Exact lookup fails when no object or multiple
+objects match. API-key lookup returns masked metadata only.
 
 ## Deferred Surfaces
 

docs/release.md

@@ -23,13 +23,14 @@ Use this checklist before publishing a Kernel Terraform provider version.
 - Review the [v1 migration guide](migration-v1.md) and include it in the release notes.
 - Use the commands and status table in `docs/acceptance.md` as the single source of truth. The manual `Acceptance` workflow runs all current packages in parallel; add each new package in the same PR as its first live test and keep live tests out of normal PR CI.
   - Process-level timeouts can bypass Go test cleanup. After an interrupted or hard-timeout run:
-    1. In the Kernel dashboard or durable API, find projects, browser pools, extensions, profiles, and proxies named `kernel-tf-*` that were created during the failed workflow run.
+    1. In the Kernel dashboard or durable API, find projects, browser pools, extensions, profiles, proxies, and API keys named `kernel-tf-*` that were created during the failed workflow run.
     2. Delete leaked browser pools first with `force=false`. If deletion conflicts with a lease, wait for the lease to end; do not force-release or recover the browser from Terraform cleanup.
     3. Delete leaked extensions after removing any durable browser-pool references to them. Do not mutate pools or running browsers implicitly.
     4. Delete leaked profiles and managed datacenter proxies after removing durable references. Do not run proxy health checks as cleanup.
-    5. Delete a leaked project only after its child resources are gone and the organization still has another active project.
-    6. Do not delete the release-owned app fixture; it is not created by the acceptance run.
-    7. Read each test-owned canonical resource ID and require a 404 before considering cleanup complete.
+    5. Delete leaked API keys with an organization-wide administrative key. Never delete the credential running the acceptance workflow.
+    6. Delete a leaked project only after its child resources are gone and the organization still has another active project.
+    7. Do not delete the release-owned app fixture; it is not created by the acceptance run.
+    8. Read each test-owned canonical resource ID and require a 404 before considering cleanup complete.
 - Verify unscoped API calls send no `X-Kernel-Project-Id` header; it is sent only when a resource-level `project_id` or the provider default resolves a project.
 - Confirm `terraform-registry-manifest.json` contains protocol `["6.0"]` for Terraform Plugin Framework.
 - Confirm the repository license before the first public release. The release workflow fails unless a non-empty `LICENSE` exists.