Credential Integration | NVIDIA Agent Policy Fabric

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.

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 for every field and to OpenShell provider profiles for how OpenShell runs each strategy.

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 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.