Origin key
An origin key names the source that manages a resource, such as a content pack or a Git repository, and the resource's identity within that source.
The key's namespace names the source, and the rest of the key names the
resource within it, as in acme:detections/okta-impossible-travel. Perpetual
assigns a resource's id. The source assigns its origin key, and uses that key
to update the resource it manages instead of creating a second one. A resource
that no source manages has no origin key, and the API returns originKey as
null. A GitOps file for the Perpetual CLI carries the key as originKey. You
set the key when you create the resource, or later through a
changeset.
Format
An origin key is {namespace}:{key}.
- The namespace is 1 to 32 characters. It starts with a lowercase letter, followed by lowercase letters, digits, or hyphens. It names the source.
- The key is 1 to 256 characters from
A-Z,a-z,0-9,.,_,~,-,/,:, and@.
The perpetual namespace is reserved for content packs Perpetual supplies. The
API rejects any key you set in it.
Uniqueness
An origin key is unique within an organization, across
every resource type and every Space. Setting a key that
another resource already holds fails with origin_key_in_use. The error names
the resource that holds the key. Two changesets can stage the same key, and the
first to commit takes it. If Perpetual cannot identify the holder when the
second commit fails, that commit fails with already_exists on the
originKey field and names no holder. A deleted resource no longer holds its
key.
Resource types
These resource types carry an origin key:
- Content: detections, dashboards, lookups, folders, integrations with their parsers and mappers, webhooks, HTTP tools, MCP servers, skills, and content packs.
- Dataset resources: connectors, tables, views, and unions.
Changing an origin key
You change an existing resource's origin key inside a changeset, with one of three operations. The change takes effect when the changeset commits.
| Operation | Input | Effect |
|---|---|---|
adopt | originKey | Sets the origin key to originKey on a resource that has none. |
release | expectedOriginKey | Clears the resource's origin key. |
rekey | expectedOriginKey, originKey | Replaces the resource's origin key with originKey. |
adopt fails with origin_key_mismatch when the resource already holds a
different key. release and rekey fail with origin_key_mismatch unless
expectedOriginKey matches the key the resource holds in your changeset.
Neither accepts an expectedOriginKey in the reserved perpetual namespace, so
you cannot release or replace a key that a Perpetual-supplied pack set.
An operation fails with origin_key_base_stale when a committed change replaced
the key after your changeset staged the resource, unless the operation sets the
same key that change committed. The failure clears once the changeset catches
up with the latest version or its conflicts are resolved, or once you discard
the resource's change.
Both errors return currentOriginKey. For origin_key_mismatch it is the key
the resource holds in your changeset. For origin_key_base_stale it is the
committed key.
Related
- Resource, the common fields every resource carries.
- Changesets, which stage an origin key change.
- Content packs. A pack Perpetual supplies, and the
content in it, hold keys in the reserved
perpetualnamespace.