Interface ActivationKey

All Known Implementing Classes:
ActivationKey.Opaque, ActivationKey.V1, ActivationKey.V2Encrypted
public sealed interface ActivationKey permits ActivationKey.V1, ActivationKey.V2Encrypted, ActivationKey.Opaque
The activation key of the Connection Coordinator specification (environment.yaml#/ActivationKey): the token a customer obtains from one provider and enters at the other provider to accept a connection.

Beta: derived from the open specification at commit bbfc763 (see the package documentation). The versioned key format (ActivationKeyV1 / ActivationKeyV2) was introduced between commits 8173027 and bbfc763; the specification publishes no example key, so the test fixtures are built from the schema's field list.

Wire format

The specification states the key "is always transported as a base64-encoded JSON string". The JSON object is discriminated on the integer version. Every version carries the cleartext envelope version + destinationEnvironmentUri.

Variants
TypeConditionReadable members
ActivationKey.V1 version == 1 and all five required fields present with the schema's types version, destinationEnvironmentUri, sharedConnectionUuid, connectionSizeMbps (Mbps), destinationAccountId
ActivationKey.V2Encrypted version == 2, destinationEnvironmentUri and encryptedContents present version, destinationEnvironmentUri. encryptedContents is ciphertext under the destination environment's public key (the specification's example algorithm is RSA-OAEP-256); this SDK holds no private key, does not decrypt it and exposes no accessor for it
ActivationKey.Opaque anything else: not base64, not JSON, not a JSON object, duplicate JSON keys, trailing content, an unlisted version, or a listed version with missing or mistyped fields the raw string; the envelope when it could be read

Decoding never rejects a key

decode(String) throws only for a null or blank argument. Every other input yields a value; an input this SDK release cannot interpret yields ActivationKey.Opaque, so a provider-issued key in a newer or provider-specific format can still be carried to the other provider unchanged.

encode() returns what the provider issued

For a decoded ActivationKey.V1 or ActivationKey.V2Encrypted, encode() returns the input string with ASCII whitespace removed (the base64 alphabet contains none, so the payload bytes are unchanged). It is not re-serialized: JSON members this SDK does not model, member order and padding survive, and the issuing provider sees the bytes it issued. For a ActivationKey.V1 created with ActivationKey.V1.builder(), encode() returns the canonical form: compact UTF-8 JSON with members in the order version, destinationEnvironmentUri, sharedConnectionUuid, connectionSizeMbps, destinationAccountId, encoded with the RFC 4648 section 4 alphabet, with padding. Decoding a canonical string and encoding it again returns the identical string.

Keys are credentials

The specification requires the receiving provider to verify that the key was presented by an authorized user of destinationAccountId, and a version 1 key is fully cleartext: its five fields are sufficient to rebuild it. toString() on every variant therefore omits destinationAccountId, sharedConnectionUuid, the ciphertext and the encoded form. Jackson serializes every variant as the empty object {} under any ObjectMapper configuration: the variants expose no JavaBean getters, and each is annotated with a serializer that writes {} (a default ObjectMapper would otherwise reject a bean with no properties, SerializationFeature.FAIL_ON_EMPTY_BEANS). Write encode() explicitly where a key must be transported.

Not to be confused with

  • fabric.model.implementation.AccessPoint.activationKey (Fabric v4, Beta): a plain string on an access point. Its value may be in this open format; pass it to decode(String) to find out.
  • networkedge DeviceVendorConfig.activationKey: a vendor licence key for a virtual device. Unrelated.
  • The Fabric service-profile authenticationKey (an AWS account id, an Azure service key, a GCP pairing key, an OCI virtual-circuit OCID): an identifier, not a structured single-use intent. Fabric v4 keeps the two as sibling fields.
Author:
ianjones

  • Method Details

    • decode

      static ActivationKey decode(String encoded)
      Decodes a key as received from a provider.

      ASCII whitespace (space, tab, CR, LF) anywhere in the input is ignored for decoding, so a key wrapped across lines by a console or an e-mail client still decodes. Both the RFC 4648 section 4 alphabet and the URL-safe section 5 alphabet are accepted, with or without padding.

      Parameters:
      encoded - the key string
      Returns:
      a ActivationKey.V1, a ActivationKey.V2Encrypted, or an ActivationKey.Opaque carrying the input
      Throws:
      NullPointerException - if encoded is null
      IllegalArgumentException - if encoded is blank

    • encode

      String encode()
      Returns:
      the string to hand to the receiving provider; see the class documentation for what each variant returns

    • envelopeVersion

      OptionalInt envelopeVersion()
      Returns:
      the envelope's version; empty only for an ActivationKey.Opaque key whose payload carried no readable integer version

    • envelopeDestinationEnvironmentUri

      Optional<String> envelopeDestinationEnvironmentUri()
      Returns:
      the envelope's destinationEnvironmentUri; empty only for an ActivationKey.Opaque key whose payload carried no readable destinationEnvironmentUri

    • destinationEnvironmentId

      default Optional<String> destinationEnvironmentId()
      The environment id named by the envelope's destinationEnvironmentUri, extracted by EnvironmentRef.environmentIdOf(String).
      Returns:
      the environment id, or empty when the envelope is unreadable or its URI contains no environments/{id} segment