External Services & Encryption Keys

External Services & Encryption Keys let an organization keep the platform’s signing keys in its own cloud KMS. The platform never holds the key material. It reaches each key through a credential the organization configures and asks the KMS to sign, and identity providers and MCP servers verify the resulting tokens against a public key set the organization controls. Manage them from Organization settings > Settings > External Services and Organization settings > Settings > Encryption Keys in the dashboard.

Customer-managed encryption keys are enabled per organization; contact Speakeasy to turn them on. Until then, neither page appears in the sidebar. Google Cloud is the only supported provider.

Access requirements

Viewing both pages requires the org:read scope, which both the Admin and Member default roles include. Creating, editing, verifying, or deleting a credential, key, or key set requires the org:admin scope, held only by the Admin role by default. Verification performs a real signing operation billed to the key’s owner, so it is rate limited per organization.

How the pieces fit

Three objects chain together:

• An external credential is how the platform authenticates into the organization’s cloud account. The platform impersonates a service account the organization nominates, so it holds no long-lived credentials of its own.
• An encryption key names one asymmetric key version in the organization’s KMS and the credential that reaches it.
• A signing key set (JSON Web Key Set, or JWKS) publishes the public half of a KMS key, so relying parties can verify the tokens the platform signs. The private half never leaves the KMS.

Set them up in that order: credential, then key, then key set.

Connect a cloud account

On the External Services page, select New External Credential, choose Google Cloud Platform, name the credential, and enter the service account to impersonate (name@project.iam.gserviceaccount.com).

Before saving, grant the platform’s own service account the roles/iam.serviceAccountTokenCreator role on that service account. The sheet shows the exact principal to grant. A missing grant is the most common reason verification fails later, so the same instructions repeat on the credential’s Overview tab.

Select Verify access on the credential to confirm the platform can still impersonate the account. The platform refuses to delete a credential while an encryption key still uses it, since the key would silently lose access to its material.

Register a KMS key

On the Encryption Keys page, select New KMS Key, choose Google Cloud KMS, and pick the external credential that reaches the key. Choose the Algorithm: RS256, the default that every JWT verifier implements, or ES256. Enter the Resource name of a specific key version, in the form projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1. Asymmetric signing keys have no primary version, so the version must be named. The resource name and algorithm cannot change after saving.

The impersonated service account needs the roles/cloudkms.signerVerifier role on the key. Select Verify signing to test the whole path: the platform reads the public key, checks the algorithm, signs a probe, and verifies the signature. A failure names its cause, such as a missing signer grant, a disabled key version, or an algorithm mismatch.

A key can later be pointed at a different credential, which changes how the platform reaches the key but not which key it is. The platform refuses to delete a key while a key set publishes from it.

Signing keys (JWKS)

Under Signing Keys (JWKS), select New Signing Key Set, name it, and pick the KMS key to publish from. Creating the set publishes that key immediately as its active signing key, so the key’s credential has to work at creation time.

Keys in a set move through a lifecycle that supports rotation without breaking outstanding tokens:

• Pending: published so verifiers can cache it, not yet signing
• Active: new tokens are signed with it
• Retired: no longer signing, still published so outstanding tokens verify; a retired key can be activated again
• Revoked: withdrawn, and tokens signed with it no longer verify

To rotate, select Publish new key on the set’s Keys tab and pick the KMS key to publish from. The new key is published as pending (or activated immediately when the set has no active key). Activate it once verifiers have cached it. The set’s Overview tab shows its audit history, including events on its keys.

Used by

• Remote Identity Providers
• User sessions and Secure with OAuth
• Audit Logs