Skip to main content

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:

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.

OperationInputEffect
adoptoriginKeySets the origin key to originKey on a resource that has none.
releaseexpectedOriginKeyClears the resource's origin key.
rekeyexpectedOriginKey, originKeyReplaces 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.

  • 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 perpetual namespace.