These examples show you how to create an access key and rotate it to a new
version.

Create and apply an access key

This example shows how to create an access key and apply it in Property Manager:

1. Get authentication details from your cloud provider.

2. Run the create an access key operation. Store the accessKeyName and requestId values. Wait for the retryAfter number of seconds before continuing to the next step.

3. Get an access key status using the stored requestId. Repeat this until processingStatus is DONE in the response. Review the accessKeyVersion object and store the link value.

{
  "processingStatus": "DONE",
  "requestedBy": "jdoe",
  "requestDate": "2021-02-26T13:34:36.715643Z",
  "accessKey": {
    "accessKeyUid": 12345,
    "link": "/cam/v1/access-keys/12345"
  },
  "accessKeyVersion": {
    "accessKeyUid": 12345,
    "version": 1,
    "link": "/cam/v1/access-keys/12345/versions/1"
  }
}

4. Wait for 10 minutes and call the link with a GET:

GET /cam/v1/access-keys/12345/versions/1

5. If necessary, repeat step 4 until deploymentStatus is ACTIVE. Store the versionGuid from the response:

{
        "accessKeyUid": 12345,
        "versionGuid": "1a2b3456-7890-12cd-345-6e7f89012g13",
        "version": 1,
        "cloudAccessKeyId": null,
        "deploymentStatus": "ACTIVE",
        "createdBy": "jdoe",
        "creationDate": "2021-02-26T13:34:37.916873Z"
    }

6. Follow the Property Manager API (PAPI) workflow to create a new property or edit an existing one. Store the propertyId and version set for the property.

7. Update the rule tree for the property to configure the originCharacteristics behavior:

   • Determine the rule and match criteria you want to use. The required default rule applies to all requests. You can also include an additional rules array and define custom match criteria.

   • Include the originCharacteristics behavior in the behaviors array of your chosen rule. Set country to the geographical location of your origin server to optimize access to it. Set the authenticationMethod to the applicable cloud provider, AWSV4 for Amazon Web Services or, GCS_HMAC_AUTHENTICATION for Google Cloud Services Set accessKeyEncryptedStorage to true to enable secure use of access keys. Include the gcsAccessKeyVersionGuid member for GCS, or the awsAccessKeyVersionGuid member for AWS and set it to the versionGuid you stored earlier.

{
  "rules": {
    "name": "default",
    "criteria": [],
    "children": [],
    "options": {
      "is_secure": true
    },
    "behaviors": [
      {
        "name": "originCharacteristics",
        "options": {
          "country": "NORTH_AMERICA",
          "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
          "accessKeyEncryptedStorage": true,
          "gcsAccessKeyVersionGuid": "1a2b3456-7890-12cd-345-6e7f89012g13"
        }
      },
      {
        "name": "cpCode",
        "options": {
          "value": {
            "id": 12345,
            "name": "my CP code"
          }
        }
      }
    ]
  }
}

8. You can further customize the rule tree in your property to meet your needs. See the PAPI feature catalog for details on available behaviors.

9. Activate your property on the STAGING network for testing.

10. When you're satisfied with your property, activate it on the PRODUCTION network to go live.

Rotate an access key to a new version

This example shows how to rotate an access key from version 1 to version 2 and apply it in Property Manager. It's a best practice to rotate your cloud provider credentials periodically. You may also need to do this if the credentials have expired or been compromised.

1. Get new authentication details from your cloud provider.

2. Create an access key version. Store the requestId returned in the response.

3. Get an access key version status using the stored requestId. Verify that processingStatus is DONE. Review the accessKeyVersion object and store the link value.

{
        "processingStatus": "DONE",
        "requestedBy": "jdoe",
        "requestDate": "2021-02-26T14:54:38.622074Z",
        "accessKeyVersion": {
            "accessKeyUid": 12345,
            "version": 2,
            "link": "/cam/v1/access-keys/12345/versions/2"
        }
    }

4. Wait for 10 minutes and call the link with a GET:

GET /cam/v1/access-keys/12345/versions/2

5. If necessary, repeat step 4 until deploymentStatus is ACTIVE. Store the versionGuid from the response.

{
        "accessKeyUid": "12345",
        "versionGuid": "2b3c4567-8901-23de-456-7f8g90123h45",
        "version": 2,
        "cloudAccessKeyId": null,
        "deploymentStatus": "ACTIVE",
        "createdBy": "jdoe",
        "creationDate": "2021-02-26T13:34:37.916873Z"
    }

6. Use the accessKeyUid and its previous version to perform a property lookup request. This shows you all of the active properties that are using this version of the key. Store the propertyId for each.

7. Use the Property Manager API to get the existing rule tree for a property that has CAM activated in the Origin Characteristics behavior. Store the response output.

8. Update the rule tree and use the existing rule tree's stored response output as the request body. Locate the originCharacteristics behavior in the request body content. Change the gcsAccessKeyVersionGuid or awsAccessKeyVersionGuid to the new versionGuid.

{
  "behaviors": [
    {
      "name": "originCharacteristics",
      "options": {
        "country": "NORTH_AMERICA",
        "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
        "accessKeyEncryptedStorage": true,
        "gcsAccessKeyVersionGuid": "2b3c4567-8901-23de-456-7f8g90123h45"
      }
    },
    {
      "name": "cpCode",
      "options": {
        "value": {
          "id": 12345,
          "name": "my CP code"
        }
      }
    }
  ]
}

9. Repeat steps 7-8 for each remaining propertyId.

10. Activate each property on the STAGING network for testing.

11. When you're satisfied, activate each updated property on the PRODUCTION network to go live.

12. After each updated property is live in production, use the CAM API to delete the old access key version. You no longer need it.