> This page is for version Dev (default). > For other versions, use one of these documentation indexes: > - Dev (default): https://docs.nvidia.com/agent-policy-fabric/dev/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/agent-policy-fabric/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/agent-policy-fabric/_mcp/server. # Credential Integration > How APF governs which providers and credentials an agent may use while OpenShell stores and injects the credential values, and APF never sees them. APF governs credentials without handling them. A signed bundle declares which providers exist, which endpoints each provider's credentials may reach, and how each credential is obtained and sent. OpenShell stores the credential values, mints or refreshes them, and injects them into approved requests. APF evaluates every request before that injection happens. ## Where APF Stops and OpenShell Starts | Responsibility | Owner | | ------------------------------------------------------------------- | ----------------------------------------------------------------- | | Declaring providers, endpoints, credential names, and auth styles | APF bundle (`Provider` documents) | | Deciding which provider types and profiles may exist on the gateway | APF interceptor | | Deciding whether a request may proceed, and rewriting its content | APF middleware | | Storing credential values | OpenShell and the credential source it uses | | Minting, refreshing, and rotating credentials | OpenShell, following the refresh strategy in the provider profile | | Injecting credentials into a request | OpenShell, after APF's decision | | Revoking credentials | The credential source | ## APF Never Sees Credentials OpenShell calls APF's middleware at the `PRE_CREDENTIALS` hook. The hook fires after OpenShell's own Layer 1 checks and before OpenShell injects provider credentials, so every request APF evaluates is credential-free. APF's audit records never contain credential material, and header mutations cannot touch credential headers. A `remove` on `authorization`, `cookie`, or any `x-openshell-credential*` header is refused. At the interceptor, OpenShell omits fields its protobuf schema marks as secret before it calls APF. APF therefore validates provider governance, not credential values. ## Declaring Credentials Each `Provider` document lists the credentials the provider uses. ```yaml apiVersion: nvidia.agent-policy-fabric.policy/v1alpha1 kind: Provider metadata: name: github title: GitHub description: GitHub REST API, read-only access to repositories and issues. spec: type: source-control endpoints: - host: api.github.com port: 443 protocol: rest access: read-only enforcement: enforce binaries: - /usr/bin/gh - /usr/bin/git credentials: - name: api_token envVars: - GITHUB_TOKEN required: true style: bearer header: Authorization source: kind: host-env name: GITHUB_TOKEN ``` | Field | Meaning | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Credential identifier. Defaults to the provider name when empty. | | `envVars` | Environment variable names the credential is exposed as. | | `style` | How the credential is sent: `bearer`, `header`, `query`, or `path`. Empty means `bearer`. The schema also accepts `basic` and `cookie`. OpenShell accepts `basic` and rejects `cookie`. | | `header` | Header name. Required for the `bearer` and `header` styles. | | `queryParam` | Query parameter name. Required for the `query` style. | | `pathTemplate` | Path template. Required for the `path` style. | | `source` | How the credential is obtained. See the next section. | | `discoverable` | Whether the credential is listed for discovery. Defaults to discoverable. | | `required` | Whether the provider needs this credential. | The `Provider` JSON Schema rejects a credential whose style is missing its companion field, and an endpoint without a host or a port. `apf-compile` and the policy service do not check these, so validate providers against the schema before you sign. ## Credential Sources The `source.kind` selects how OpenShell obtains the value. APF projects each source into the provider profile's refresh strategy or token grant block. | `source.kind` | Projected as | Meaning | | ----------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | | `host-env` | No refresh block | A static credential supplied in the host environment. | | `oauth2` with `grant: client-credentials` | Refresh strategy `oauth2_client_credentials` | Minted with an OAuth2 client credentials grant at `tokenUrl`. | | `oauth2` with `grant: refresh-token` | Refresh strategy `oauth2_refresh_token` | Refreshed with an OAuth2 refresh token at `tokenUrl`. | | `external` | Refresh strategy `external` | A credential that a process outside APF and OpenShell refreshes. | | `google-service-account-jwt` | Refresh strategy `google_service_account_jwt` | Minted by exchanging a signed service account JWT. | | `aws-sts-assume-role` | Refresh strategy `aws_sts_assume_role` | Minted by assuming an AWS IAM role through STS. | | `token-grant` | Token grant block | Minted at use time through an OAuth2 token endpoint, authenticated with a JWT-SVID. | Refresh sources accept `refreshBeforeSeconds`, `maxLifetimeSeconds`, and, where applicable, `scopes`, `material`, and `additionalOutputs`. Refer to [Policy Schemas](/agent-policy-fabric/reference/policy-schemas#provider) for every field and to [OpenShell provider profiles](https://docs.nvidia.com/openshell/latest/how-it-works/providers/profiles) for how OpenShell runs each strategy. > **Note** > > Some source fields are not carried into the OpenShell provider profile in this release. The `name` of a `host-env` or `external` source is not projected, so OpenShell uses the credential's `envVars`. The environment variable bindings in an `oauth2` source's `parameters` map are not projected either. Each parameter key becomes a required refresh material entry, marked secret when its name suggests a secret. ## Binding Credentials to Endpoints A `SandboxPolicy` network endpoint carries OpenShell's credential controls. | Endpoint field | Effect | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_body_credential_rewrite` | Lets OpenShell rewrite credential placeholders in textual request bodies. | | `websocket_credential_rewrite` | Lets OpenShell rewrite credential placeholders in client WebSocket text messages. | | `credential_binding.provider` | Accepted by the authoring schema, but not projected in this release. OpenShell always receives no binding. | | `allow_uninspected_credentials` | Accepted by the authoring schema, but not projected in this release. OpenShell always receives `false`, so credential-bearing traffic never uses a path OpenShell cannot inspect. | ## Governing Providers at the Gateway When APF governs an OpenShell gateway, the interceptor enforces the bundle's provider catalog. | Operation | APF behavior | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CreateProvider`, `UpdateProvider` | Allowed only if the provider's type names a profile the bundle manages. | | `ImportProviderProfiles` | Allowed only for profiles the bundle manages, and only when each profile's content matches the bundle's copy for that ID. APF leaves `resourceVersion` and annotations out of the comparison, because they are storage metadata, not bundle content. | | `UpdateProviderProfiles` | Allowed only for a profile the bundle manages whose content matches the bundle's copy. `resourceVersion` and annotations are left out of the comparison. | | `DeleteProviderProfile` | Always denied. | The content check applies to every caller, so a bundle-managed profile cannot be changed in OpenShell to differ from the bundle. APF's own provider profile reconciler writes the bundle's profiles, so its imports and updates pass. Refer to [Gateway Interceptor](/agent-policy-fabric/integrations/openshell/gateway-interceptor) for the reason codes. ## Credential Issuance APF does not issue, rotate, or revoke credentials. OpenShell mints, refreshes, and injects them after APF has decided, and your credential source revokes them, as the table above shows. ## Next Steps * To author provider documents, refer to [Sandbox Policies](/agent-policy-fabric/author-policies/sandbox-policies#providers).