Signing Flows custom apps from the CLI

Signing a Flows custom app proves who built the bundle and binds the signature to the exact bytes deployed. The platform rejects the version if anything in the bundle changes after signing, or if the signing key isn’t registered. This guide has two parts. First, generate and register a signing key. Then upload, sign, and publish each version of the app. Use this guide if you’re a certified Flows builder and you publish custom apps with the Cognite CLI.

Signatures required to publish

Every publish needs a developer signature. Projects with Dev status need only that signature. Production Cognite Data Fusion (CDF) projects without Dev status need both that signature and Cognite’s app certification signature (.cert.sig) from Application certification. Each signature is tied to the exact bundle bytes. This guide covers the developer signature only.

Signature	What it proves
Developer signature	A certified developer built this bundle for this CDF project.
App certification signature	Cognite has reviewed and approved this production bundle.

Request Dev status before you publish to a non-production project.

Prerequisites

The latest Cognite CLI (npx @cognite/cli@latest).
A Flows custom app with app.json (with infra set to appsApi).
Access to the CDF project you’ll deploy to.
Builder certification, or signing instructions from the team reviewing your app.
Application certification if you’re publishing to a production project and need Cognite’s .cert.sig.

A developer signature is not the same as application certification. Production apps still need Cognite’s application certification signature before they can be published to production projects.

Generate and register a signing key

Do this after you claim the builder certificate. Every publish needs a developer signature from a key that Cognite has registered. Generate a signing key and submit the Zendesk URL that the CLI prints. You need one registered key to publish apps to any CDF project.

Generate a signing key

npx @cognite/cli@latest keys generate --interactive

When prompted for a key ID (kid), give the key a short name for this machine, such as juno-laptop. The key expires in 12 months. On macOS, the private key goes in Keychain (a password prompt is expected). On Windows, it goes in Credential Manager. Don’t email the .pub.pem file. The Zendesk URL already includes the public key.These flags change how the CLI collects the name and how you get the Zendesk URL.

Flag	What it does
`--interactive`	Prompts you to Open in browser or Copy link. Opens a pre-filled Zendesk form. Does not submit the form.
`--copy-link`	Copies the Zendesk URL with no prompt.
`--kid`	Sets the key ID. Use a short name for this machine.
`--email`	Sets the email address on the Zendesk form.

If you pass --kid and --email together, the CLI skips prompts and prints the URL plus a YAML block. Use the URL. Don’t paste YAML into a blank ticket.

The private key stays on your machine. Don’t share it, commit it, export it from Keychain, or send it to Cognite.

Submit the Zendesk form from the URL that keys generate printed. Don’t paste YAML into a blank ticket.Support checks that you completed Cognite Flows Foundation and the hands-on workshop, then replies when they add the key. New keys become available on weekdays during business hours in Central European Time (CET). Until then, apps status can show KEY_NOT_IN_REGISTRY. If publish fails with a 403 that mentions CDF capabilities, that message is generic. It is not an access problem. See 403: signing key is not in the public key registry.

When support has added the key and it is available, you can publish apps with a developer signature.

Upload, sign, and publish the app

After your public key is registered, use these steps to upload, sign, and publish each version of the app.

Build and upload

From your app folder:

npm run build
npx @cognite/cli@latest apps deploy --interactive

apps deploy packages dist/, uploads it as a DRAFT, and keeps a copy of the exact bytes at .cognite-bundles/<externalId>-<versionTag>.zip so signing operates on what the platform actually received. The app scaffold gitignores .cognite-bundles/. Don’t commit bundle files from that folder.

Sign the bundle

npx @cognite/cli@latest apps sign

With no arguments, apps sign uses externalId and versionTag from app.json. It finds the matching .cognite-bundles/<app>-<version>.zip, writes <bundle>.dev.sig next to it, and submits the signature to the platform. Override with --signing-identity <kid>, --scope <org>/<project>, or an explicit bundle path.Run apps status to verify the signature was accepted before you publish.

Commit before signing so the source-to-signature link stays auditable. Tag the commit with the app version:

git tag "v$(jq -r .versionTag app.json)" -m "Signed deployment"
git push origin --tags

Publish

npx @cognite/cli@latest apps publish .

apps publish transitions the version from DRAFT to PUBLISHED. Signatures were already submitted by apps sign; publish re-submits any local .dev.sig (and .cert.sig if present) as a safety net, then flips the lifecycle state.

Confirm

npx @cognite/cli@latest apps status .

The command shows the lifecycle state and every signature the platform has on record for the current version. Each entry includes the signing identity (kid), the role (developer or certifier), the time the signature was issued, and the platform’s verdict.You’ll see one of three shapes depending on where you are in the flow:Before apps deploy:

Status:  not deployed yet

Run `npx @cognite/cli apps deploy` to upload this version.

After apps deploy, before apps sign + apps publish:

Status:  DRAFT

Signatures: none stored

Run `npx @cognite/cli apps publish .` to publish this version.

After a clean publish:

App:     Sign Test App (sign-test-app)
Version: 0.0.3  (local)
Status:  PUBLISHED

Signatures:
  acme-dev-001    (developer, signed 2026-05-27T13:22:37.000Z) — VALID
  cognite-cert-1  (certifier, signed 2026-05-27T13:25:10.000Z) — VALID

A verdict other than VALID means the platform won’t accept that signature for serve-time verification. The verdict table explains each result and what to do.

Verdict	What it means	What to do
`VALID`	Signature verifies and the key is in the registry and in date.	Nothing — this is the expected state.
`REVOKED`	The signing key has been revoked since the signature was submitted.	Re-sign with a current key, then publish a new version.
`EXPIRED`	The signing key was in date when signed, but has since expired.	Rotate the key (see Rotate or replace a key) and re-sign.
`SIGNED_BEFORE_KEY_ISSUED`	The signature’s `iat` timestamp predates the key’s registration. Clock skew, or a stale key.	Re-sign with the current system clock. If the clock is correct, contact Cognite.
`IAT_IN_FUTURE`	The signature’s `iat` timestamp is in the future. Usually clock skew on the signing machine.	Fix the signing machine’s clock, then re-sign and re-publish.
`BUNDLE_TOO_OLD`	The bundle’s signature is older than the platform’s minimum-age policy.	Re-sign the current bundle and re-publish.
`KEY_NOT_IN_REGISTRY`	The `kid` isn’t in the public key registry, or isn’t available yet.	Confirm the `kid` with `keys list`. Wait until the key is available on a weekday during business hours, Central European Time. See 403: signing key is not in the public key registry.

Verify the version is PUBLISHED and your developer signature appears as VALID for the expected kid. Anything else needs action before the version will serve.

Production certification (Cognite signature)

Production CDF projects without Dev status need both a developer signature and an app certification signature. The two signatures are independent. Cognite signs the same bundle bytes with their own key and returns the signature to you. Complete the Upload, sign, and publish the app steps through Sign the bundle, then add these steps before you publish the application:

Submit the app for review

From your app folder, on a clean commit:

npx @cognite/cli@latest apps submit

apps submit packages a source archive (src-<sha>.zip), copies the deploy bundle into dist/submit/, and opens a pre-filled Zendesk request with the app metadata. Attach everything in dist/submit/ plus a screen recording of the app, then submit.

The command will fail if your working tree has uncommitted changes — the source archive has to match the committed code exactly. Commit first, then re-run.

Receive the certification signature from Cognite

After Cognite reviews and approves the bundle, your Zendesk contact replies with a .cert.sig file. Save it to your app’s .cognite-bundles/ folder next to the deploy bundle, named <externalId>-<versionTag>.cert.sig.For example, for app sign-test-app version 0.0.3:

.cognite-bundles/
  sign-test-app-0.0.3.zip          ← created by apps deploy
  sign-test-app-0.0.3.zip.dev.sig  ← created by apps sign
  sign-test-app-0.0.3.zip.cert.sig ← from Cognite, save here

To open .cognite-bundles/ in your file manager from the app folder:

macOS
Windows
Linux

open .cognite-bundles

explorer .cognite-bundles

xdg-open .cognite-bundles

Don’t commit .cert.sig to git. The scaffold gitignores .cognite-bundles/ for this reason.

Publish

npx @cognite/cli@latest apps publish .

apps publish picks up both .dev.sig and .cert.sig, submits the certifier signature, and transitions the version to PUBLISHED.Run apps status . to confirm both signatures show as VALID.

Sign again when the bundle changes

The signature is bound to the exact bytes of the bundle. Anything that changes the bundle invalidates the signature:

Re-running npm run build
Editing files in dist/ or manifest.json
Bumping the app version

Re-run apps deploy, apps sign, and apps publish in order. deploy overwrites the bundle file at the same path, so the next sign picks up the new bytes automatically.

Rotate or replace a key

Generate a new key when the old one expires, you move to a new machine, or you suspect the private key is compromised:

npx @cognite/cli@latest keys generate --interactive.
Register the new public key.
Sign new bundles with the new key.
Ask your Cognite contact to revoke the old key if needed.

Previously published apps stay published. Rotating your local key doesn’t invalidate signatures already accepted by the platform.

Troubleshooting

No signing identities were found

Run npx @cognite/cli@latest keys generate --interactive, then retry the signing command.

Publish fails with bundle hash mismatch

The bytes you signed don’t match what the platform received. Run these commands in order:

npx @cognite/cli@latest apps deploy — refreshes .cognite-bundles/<app>-<version>.zip with the bytes the platform has.
npx @cognite/cli@latest apps sign — signs the refreshed bundle.
npx @cognite/cli@latest apps publish . — submits the new signature.

Don’t manually repackage the bundle.

apps status shows KEY_NOT_IN_REGISTRY

apps sign stores the signature even if the key isn’t in the registry yet. Wait until the key is available on a weekday during business hours, Central European Time. Don’t sign or publish again while you wait. apps status flips to VALID on its own. If publish returned 403, see 403: signing key is not in the public key registry and run apps publish again after the key is available.

403: signing key is not in the public key registry

If publish fails with:

signature (role=developer, kid=jsmith-dev-001): signing key used to create the signature is not in the public key registry. | code: 403 | X-Request-ID: ...
  You don't have the required CDF capabilities. Please contact your CDF admin.

The first line is the cause: that kid isn’t in the public key registry. The second sentence is a generic message the CLI shows for any 403. It is not an access problem. Don’t contact your CDF administrator for this error.Either you signed with a different local key than the one you registered, or the registered key is not available yet. Run npx @cognite/cli@latest keys list. If you signed with the wrong key, sign again with --signing-identity <kid> and publish again. If you used the registered key, wait until the key is available on a weekday during business hours, Central European Time (CET), then run apps publish again. You don’t need to sign again.If the error continues during business hours, Central European Time, contact Cognite support.

apps status shows IAT_IN_FUTURE or SIGNED_BEFORE_KEY_ISSUED

The signature timestamp doesn’t line up with the key’s registration window. Almost always clock skew on the signing machine. Make sure your system clock is correct, then re-run apps sign and apps publish.

Publish fails with two signatures required

You’re targeting a production project that requires both a developer and an app certification signature. Follow Production certification to submit for review and add the .cert.sig Cognite returns.

Multiple signing keys

Run npx @cognite/cli@latest keys list, find the correct kid, and pass it with --signing-identity <kid>.

Lost access to Mac or Keychain

Generate a new key on the replacement machine and register the public key. Ask your Cognite contact to revoke the old key if it may be compromised.

​Signatures required to publish

​Prerequisites

​Generate and register a signing key

​Upload, sign, and publish the app

​Production certification (Cognite signature)

​Sign again when the bundle changes

​Rotate or replace a key

​Troubleshooting

​Related topics

Signatures required to publish

Prerequisites

Generate and register a signing key

Upload, sign, and publish the app

Production certification (Cognite signature)

Sign again when the bundle changes

Rotate or replace a key

Troubleshooting

Related topics