Credential Sources

Credential sources store the secret material that later gets projected into outbound auth flows.

Sources are created once per team and then referenced by sourceRef from sandbox or template network policy.

The API surface is:

POST creates a new source and returns 409 Conflict when the name already exists. PUT rotates an existing source and returns 404 Not Found when the name does not exist.

Resolver Kinds#

Resolver kind is immutable for a source name. Rotate the secret material within the same resolver kind. To change from one resolver kind to another, create a new source and update the affected bindings to reference that new source.

Storage Backends#

Credential source storage is selected by the platform, not by the credential source API caller.

Sandbox0 supports encrypted PostgreSQL storage and Vault-compatible storage backends. API users keep sending the same write-only spec in both modes. For self-hosted backend configuration, see Self-hosted Configuration.

Create A Source#

go
source, err := client.CreateCredentialSource(ctx, apispec.CredentialSourceWriteRequest{
  Name: "github-source",
  ResolverKind: apispec.CredentialSourceResolverKindStaticHeaders,
  Spec: apispec.CredentialSourceWriteSpec{
      StaticHeaders: apispec.NewOptStaticHeadersSourceSpec(apispec.StaticHeadersSourceSpec{
          Values: apispec.NewOptStaticHeadersSourceSpecValues(
              apispec.StaticHeadersSourceSpecValues{
                  "token": os.Getenv("GITHUB_TOKEN"),
              },
          ),
      }),
  },
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(source.Name)

List Sources#

Read APIs return metadata only. Use list to discover source names, resolver kinds, status, and current versions.

go
sources, err := client.ListCredentialSources(ctx)
if err != nil {
  log.Fatal(err)
}
for _, source := range sources {
  fmt.Printf("- %s (%s) version=%d\n", source.Name, source.ResolverKind, source.CurrentVersion.Or(0))
}

Get Source Metadata#

Use get when you know the source name and want the current metadata record without listing everything.

go
source, err := client.GetCredentialSource(ctx, "github-source")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("%s version=%d status=%s\n", source.Name, source.CurrentVersion.Or(0), source.Status.Or(""))

Update Or Rotate A Source#

Use PUT /api/v1/credential-sources/{name} to replace the source contents while keeping the same source name and resolver kind. Existing bindings continue to point at that source name.

Sources are reusable. Rotate the source once, then keep bindings and credential rules stable by continuing to reference the same sourceRef. Already-claimed sandboxes pick up the new source version through realtime ctld network-cache invalidation. If invalidation delivery is interrupted by a restart or database notification outage, the binding's resolved-material cache TTL remains the fallback consistency bound. The default TTL is 5 minutes, or the binding's cachePolicy.ttl when set.

go
source, err := client.UpdateCredentialSource(ctx, "github-source", apispec.CredentialSourceWriteRequest{
  ResolverKind: apispec.CredentialSourceResolverKindStaticHeaders,
  Spec: apispec.CredentialSourceWriteSpec{
      StaticHeaders: apispec.NewOptStaticHeadersSourceSpec(apispec.StaticHeadersSourceSpec{
          Values: apispec.NewOptStaticHeadersSourceSpecValues(
              apispec.StaticHeadersSourceSpecValues{
                  "token": os.Getenv("ROTATED_GITHUB_TOKEN"),
              },
          ),
      }),
  },
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(source.Name, source.CurrentVersion.Or(0))

Delete A Source#

Delete only succeeds after no sandbox or template credential binding still references the source.

go
_, err := client.DeleteCredentialSource(ctx, "github-source")
if err != nil {
  log.Fatal(err)
}
fmt.Println("deleted github-source")

Next Steps#