IoT Token Access Control API v1

For Internet of Things products, manage the public keys that authenticate JSON web token requests.

Learn more:


Overview

The Token Access Control API allows you to programmatically create, manage, and store collections of public keys. It lets you upload public keys into key collections, activate key collections in the staging environment before going live, and create key collection versions to enable frictionless public key rotation for property configurations.

Who should use this API

Akamai provides APIs for developers, DevOps, and operations personnel as an alternative to using Akamai Control Center. This API provides the same functions as the Token Access Control application in Control Center.

Use this API to automate management and rotation of public keys used by the IoT products to authenticate and authorize clients sending requests with JSON web tokens (JWT) to origin servers.

Typically, you need to refer to a key collection in the JWT behaviors of IoT properties to indicate the public keys that you want to use to check the integrity of JWT signatures in client requests.

You can also rotate public keys that your properties use. Independent of your property’s life cycle, the Token Access Control API lets you add secondary public keys and create versions of property-referenced key collections and update public keys stored in them.

Get started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API services named IoT Token Access Control Key Collections and IoT Token Access Control Activations, and set the access levels to READ-WRITE.

API concepts

To understand this API’s various URL resources and the data it exchanges, you need to familiarize yourself with these concepts.

  • Key collection. A namespace that stores versions of public keys and indicates the ones that are active in the staging and production environments. You refer to a key collection in the JWT or JWT Verification behaviors of your IoT property. See the Detailed Key collection object.

  • Key collection version. A set of public keys within a key collection. By activating a version in the staging or production environment, you tell the associated key collection to use this version’s public keys to verify JWTs in client requests. Also, creating and activating versions of your property-referenced key collection automatically updates the public keys that this property uses. See the Key collection version object.

  • Activation. An object that deploys a key collection version in the staging or production environment. Note that you can only have one key collection version active in each of these environments. By activating a key collection version, you deactivate the previous one. See the Activation object.

Verify a web token

JSON web token is an open standard RFC 7519 that defines a compact and self-contained method for securely transmitting JSON-encoded information between parties. At Akamai, you can use JWTs to quickly identify and authorize OTA Updates and Edge Connect clients who send requests to origin servers.

A JWT contains information about an entity in the form of claims and combines three elements encapsulated in JSON objects:

  • Header. Contains information about the media type of the JWT and the hashing algorithm used for encoding the JWT.

  • Payload. Contains the actual statements represented as public claims that two parties exchange. Currently, the IoT products support the use of pre-defined registered and private claims. For more information, see IoT-supported registered claims.

  • Signature. Ensures the proper identification of the request sender and protects the request from being tampered with. Note that the IoT products support verifying JWT signatures generated with the RS256 and ES256 signing algorithms. For more information, see Keys and JWT signing algorithms.

JWTs are stateless, which means that incoming JWT requests can be validated on the spot. You don’t have to store session states on the server and load user information from a database or cache. This immediate validation increases the scalability of your system and provides an overall faster client-server experience.

Akamai verifies JWT signatures at the edge, which negates the need to go back to origin for verification and offloads your identity provider. This behavior also contributes to improved security by allowing edge servers to filter out unauthorized requests before they can reach your origin infrastructure.

The IoT products support the use of RSA or ECDSA private and public key pairs for JWT signature verification. This ensures the data in the JWT payload hasn’t been modified by third parties. You first sign a JWT by using a private key. The IoT products then verify the integrity of the JWT by using one of the public keys that you upload through the Token Access Control API.

Based on your JWT claim configuration, the IoT products check the token for the presence of claims and validate the value of each present claim. If the optional claims are present and their expected values are correct, JWT validation succeeds and the system allows the entity issuing the JWT to access the requested resources.

Keys and JWT signing algorithms

The IoT products support verification of JWT signatures generated with these algorithms:

  • RS256. RSA Digital Signature Algorithm with the SHA–256 hash function. It’s an asymmetric algorithm that uses a pair of RSA private and public keys to generate and validate JWT signatures. For IoT, you can use only RSA keys with a key length between 1024 and 4096 bits. See JWT algorithms.

  • ES256. Elliptic Curve Digital Signature Algorithm with the P–256 curve and the SHA–256 hash function. It’s an asymmetric algorithm that uses a pair of ECDSA private and public keys to generate and validate JWT signatures. For IoT, you can use only ECDSA keys using the P–256 (secp256k1) curve. See JWT algorithms.

Rotate public keys

Securely managing public keys for IoT services that you use is an important part of the Token Access Control API. It allows for key rotation to cover situations when you change the private key that signs your tokens, or your public key has been compromised. The key rotation process relies on the fact that an IoT property can use either a primary or secondary key to validate requests. If a primary key fails to validate the signature of a JWT, the IoT property tries a secondary key to validate the same token.

To rotate a primary public key, you can create a version of the key collection that your property uses and add a secondary key. This allows for a transition period when edge servers validate JWTs signed with the old and new private keys. After you’ve decided to entirely retire the primary public key, you can create and activate another key collection version where the secondary public key becomes the primary one.

Note that you don’t need to version your IoT property configuration to update the public keys it uses to validate JWTs. The JWT behavior in your property always points to the keys stored in the active version of the previously indicated key collection.

API workflows

This section presents the steps that you need to follow to create a key collection, start using public keys to verify JWT signatures in client requests, and update the key collection used by your property.

Suppose a company issues JWTs to identify IoT Edge Connect clients and authorize them to access specific topics. The company needs to provide a key collection with a public key in the property’s JWT behavior to make sure that the JWTs in client requests are properly validated. Here are the steps to do that:

  1. Create a key collection.

  2. Create a key collection version and set the primaryKey object member.

  3. Optionally, activate the key collection version on staging.

  4. Refer to the key collection in the property’s JWT behavior.

  5. Activate the key collection version on production.

If for security reasons, the company decides to rotate public key used by the property, it can simply do so by updating the key collection referenced in the JWT behavior. Here are the steps to do that:

  1. Create a key collection version and set the secondaryKey object member.

  2. Optionally, activate the key collection version on staging.

  3. Activate the key collection version on production.

  4. Create a key collection version where you replace the primaryKey value with the secondaryKey value.

  5. Optionally, activate the key collection version on staging.

  6. Activate the key collection version on production.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Key Collections  
List key collections GET /jwt-api/v1/key-collections
Create a key collection POST /jwt-api/v1/key-collections
View a key collection GET /jwt-api/v1/key-collections/{collectionId}
Create a key collection version POST /jwt-api/v1/key-collections/{collectionId}/versions
View a key collection version GET /jwt-api/v1/key-collections/{collectionId}/versions/{versionId}
Activations  
List activations GET /jwt-api/v1/activations{?collectionId}
Activate a key collection version POST /jwt-api/v1/activations

List key collections

Returns a list of key collections for the associated account. Also, for each returned collection, it specifies if any key collection versions are active in the staging and production environments.

GET /jwt-api/v1/key-collections

Status 200 application/json

Object type: KeyCollection

Download schema: keyCollectionsRs.json

Response body:

[
    {
        "id": 12,
        "name": "EdgeConnectKeySet",
        "createdDate": 1522747964221,
        "createdBy": "keyAdministrator_EdgeConnect",
        "staging": {
            "id": 16,
            "no": 2,
            "startTime": 1522748072292,
            "algorithm": "RSA"
        },
        "production": {
            "id": 11,
            "no": 1,
            "startTime": 1522748047092,
            "algorithm": "RSA"
        },
        "jwt": "12"
    },
    {
        "id": 15,
        "name": "OTAUpdatesKeySet",
        "createdDate": 1522251911450,
        "createdBy": "keyAdministrator_OTA",
        "staging": {
            "id": 15,
            "no": 4,
            "startTime": 1546613339629,
            "algorithm": "RSA"
        },
        "production": {
            "id": 14,
            "no": 1,
            "startTime": 1522252265017,
            "algorithm": "ECDSA_P_256"
        },
        "jwt": "15"
    }
]

Create a key collection

Creates an empty key collection. To upload public keys to a newly created collection, run the Create a key collection version operation. Also, store the id of the key collection for when you want to start referring to this collection in the JWT behavior of your property. See API concepts.

POST /jwt-api/v1/key-collections

Content-Type: application/json

Object type: KeyCollection

Download schema: keyCollectionRQ.json

Request body:

{
    "name": "EdgeConnectKeySet"
}

Status 201 application/json

Object type: KeyCollection

Download schema: keyCollectionRS.json

Response body:

{
    "id": 12,
    "name": "EdgeConnectKeySet",
    "createdDate": 1522747964221,
    "createdBy": "keyAdministrator_EdgeConnect",
    "jwt": "12"
}

View a key collection

Returns details about the key collection, listing all created versions and specifying the ones active in the production and staging environments. If you don’t already have the collectionId, run the Get a collection operation and use the appropriate id value from the returned array.

GET /jwt-api/v1/key-collections/{collectionId}

Sample: /jwt-api/v1/key-collections/1

Parameter Type Sample Description
URL path parameters
collectionId Integer 1 The identifier of the key collection.

Status 200 application/json

Object type: DetailedKeyCollection

Download schema: keyCollectionWithVersionsRS.json

Response body:

{
    "id": 12,
    "name": "test_collection",
    "staging": {
        "id": 11,
        "no": 1,
        "startTime": 1546613339629,
        "algorithm": "RSA"
    },
    "production": {
        "id": 12,
        "no": 2,
        "startTime": 1522252265017,
        "algorithm": "ECDSA_P_256"
    },
    "versions": [
        {
            "id": 11,
            "collectionId": 12,
            "no": 1,
            "description": "Key Collection Version no1",
            "createdDate": 1546613339629,
            "createdBy": "user",
            "stagingStatus": "ACTIVE",
            "productionStatus": "INACTIVE",
            "algorithm": "RSA"
        },
        {
            "id": 12,
            "collectionId": 12,
            "no": 2,
            "description": "Key Collection Version no2",
            "createdDate": 1522252265017,
            "createdBy": "user",
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "algorithm": "ECDSA_P_256"
        },
        {
            "id": 13,
            "collectionId": 12,
            "no": 3,
            "description": "Key Collection Version no3",
            "createdDate": 1522252256725,
            "createdBy": "user",
            "stagingStatus": "INACTIVE",
            "productionStatus": "INACTIVE",
            "algorithm": "ECDSA_P_256"
        }
    ]
}

Create a key collection version

Creates a version of the key collection. This lets you provide primary and secondary public keys to verify JWTs passed in client requests. If you don’t already have the collectionId, run the Get a collection operation and use the appropriate id value from the returned array. Also, to start using the public keys on staging or production, run the Activate this key collection version operation.

POST /jwt-api/v1/key-collections/{collectionId}/versions

Sample: /jwt-api/v1/key-collections/1/versions

Content-Type: application/json

Object type: Version

Download schema: pemPublicKeysRQ.json

Request body:

{
    "description": "A key for IoT Edge Connect ",
    "primaryKey": "-----BEGIN PUBLIC KEY-----\nsamplepublickey\n-----END PUBLIC KEY-----"
}
Parameter Type Sample Description
URL path parameters
collectionId Integer 1 The identifier of the key collection.

Status 200 application/json

Object type: Version

Download schema: keyCollectionVersionRS.json

Response body:

{
    "id": 2,
    "collectionId": 12,
    "no": 1,
    "description": "A version active in the staging environment. ",
    "createdDate": 1522252256725,
    "createdBy": "keyAdministrator_EdgeConnect",
    "stagingStatus": "ACTIVE",
    "productionStatus": "INACTIVE",
    "algorithm": "ECDSA_P_256"
}

View a key collection version

Returns details about the key collection version. It returns the public keys the version uses to verify JWTs and reports on whether they’re are active in the production and staging environments.

GET /jwt-api/v1/key-collections/{collectionId}/versions/{versionId}

Sample: /jwt-api/v1/key-collections/2/versions/9

Parameter Type Sample Description
URL path parameters
collectionId Integer 2 The identifier of the key collection.
versionId Integer 9 The identifier of the key collection version.

Status 200 application/json

Object type: DetailedVersion

Download schema: keyCollectionVersionDetailsRS.json

Response body:

{
    "collectionId": 12,
    "versionId": 12,
    "versionNo": 1,
    "primaryKey": "-----BEGIN PUBLIC KEY-----\nsamplepublickey\n-----END PUBLIC KEY-----",
    "description": "The first version of the collection with a primary key for Edge Connect.",
    "staging": {
        "activatedBy": "keyAdministrator_EdgeConnect",
        "activatedOn": 1522748072292,
        "status": "ACTIVE"
    },
    "production": {
        "activatedBy": "keyAdministrator_EdgeConnect",
        "activatedOn": 1522748047092,
        "status": "ACTIVE"
    },
    "algorithm": "RSA",
    "algorithmDetails": "512 bits"
}

List activations

Returns a list of activations for the key collection. If you don’t already have the collectionId, run the Get key collections operation and use the appropriate id from the returned array.

GET /jwt-api/v1/activations{?collectionId}

Sample: /jwt-api/v1/activations?collectionId=50

Parameter Type Sample Description
Required query parameters
collectionId Integer 50 The identifier of the key collection.

Status 200 application/json

Object type: Activation

Download schema: activationsRS.json

Response body:

[
    {
        "id": 1,
        "environment": "STAGING",
        "state": "DONE",
        "keyCollectionVersionId": 12,
        "keyCollectionVersionNo": 1,
        "startTime": 1522748047092,
        "activatedBy": "keyAdministrator_EdgeConnect"
    },
    {
        "id": 2,
        "environment": "PRODUCTION",
        "state": "DONE",
        "keyCollectionVersionId": 12,
        "keyCollectionVersionNo": 1,
        "startTime": 1522748072292,
        "activatedBy": "keyAdministrator_EdgeConnect"
    }
]

Activate a key collection version

Deploys the version of a key collection in the staging or production environment. Note that a key collection uses the public keys from its active version to validate JWTs in client requests. See API concepts.

POST /jwt-api/v1/activations

Content-Type: application/json

Object type: Activation

Download schema: activationRQ.json

Request body:

{
    "environment": "PRODUCTION",
    "keyCollectionVersionId": 12
}

Status 201 application/json

Object type: Activation

Download schema: activationRS.json

Response body:

{
    "id": 1,
    "environment": "PRODUCTION",
    "state": "DONE",
    "keyCollectionVersionId": 12,
    "keyCollectionVersionNo": 1,
    "startTime": 1522748047092,
    "activatedBy": "keyAdministrator_EdgeConnect"
}

If you don’t already have the keyCollectionVersionId value:

  1. Run the List key collections operation.

  2. Find the appropriate key collection in the returned array and store its id value.

  3. Use the id as a collectionId and run the View a key collection operation.

  4. Find the appropriate version in the returned versions array and store its id value.

  5. Use the id as a keyCollectionVersionId and run the Activate a version operation.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

KeyCollection

Contains basic information about a key collection, including versions that are active in the staging and production environments and the types of public keys they use to validate JWT signatures.

Download schema: keyCollectionRS.json, keyCollectionRQ.json

Sample GET response:

{
    "id": 12,
    "name": "EdgeConnectKeySet",
    "createdDate": 1522747964221,
    "createdBy": "keyAdministrator_EdgeConnect",
    "jwt": "12"
}

KeyCollection members

Member Type GET POST Description
KeyCollection: Contains basic information about a key collection, including versions that are active in the staging and production environments and the types of public keys they use to validate JWT signatures.
createdBy String The username who created the key collection.
createdDate Integer An epoch timestamp marking when the key collection was created.
id Integer The identifier of the key collection.
jwt String A string version of this key collection’s id value.
name String A descriptive label for the key collection.
production KeyCollection.production Provides information about the key collection version currently active in the production environment.
staging KeyCollection.staging Provides information about the key collection version currently active in the staging environment.
KeyCollection.production: Provides information about the key collection version currently active in the production environment.
algorithm Enumeration The encryption algorithm of the public keys that the version uses in this environment to validate JWT signatures, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version.
startTime Integer An epoch timestamp marking when the key collection version was created.
KeyCollection.staging: Provides information about the key collection version currently active in the staging environment.
algorithm Enumeration The encryption algorithm of the public keys that the version uses in this environment to validate JWT signatures, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version.
startTime Integer An epoch timestamp marking when the key collection version was created.

DetailedKeyCollection

Contains detailed information about a key collection, including all its versions as well as those active in the staging and production environments. It also shows the type of public keys these versions use to validate JWT signatures.

Download schema: keyCollectionWithVersionsRS.json

Sample GET response:

{
    "id": 12,
    "name": "test_collection",
    "staging": {
        "id": 11,
        "no": 1,
        "startTime": 1546613339629,
        "algorithm": "RSA"
    },
    "production": {
        "id": 12,
        "no": 2,
        "startTime": 1522252265017,
        "algorithm": "ECDSA_P_256"
    },
    "versions": [
        {
            "id": 11,
            "collectionId": 12,
            "no": 1,
            "description": "Key Collection Version no1",
            "createdDate": 1546613339629,
            "createdBy": "user",
            "stagingStatus": "ACTIVE",
            "productionStatus": "INACTIVE",
            "algorithm": "RSA"
        },
        {
            "id": 12,
            "collectionId": 12,
            "no": 2,
            "description": "Key Collection Version no2",
            "createdDate": 1522252265017,
            "createdBy": "user",
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "algorithm": "ECDSA_P_256"
        },
        {
            "id": 13,
            "collectionId": 12,
            "no": 3,
            "description": "Key Collection Version no3",
            "createdDate": 1522252256725,
            "createdBy": "user",
            "stagingStatus": "INACTIVE",
            "productionStatus": "INACTIVE",
            "algorithm": "ECDSA_P_256"
        }
    ]
}

DetailedKeyCollection members

Member Type Required Description
DetailedKeyCollection: Contains detailed information about a key collection, including all its versions as well as those active in the staging and production environments. It also shows the type of public keys these versions use to validate JWT signatures.
id Integer The identifier of the key collection.
name String A descriptive label for the key collection.
production DetailedKeyCollection.production Contains information about the key collection version that’s active in the production environment.
staging DetailedKeyCollection.staging Contains information about the key collection version that’s active in the staging environment.
versions DetailedKeyCollection.versions[] Contains information about a key collection version, including the type of public keys it uses to validate JWT signatures, and whether it’s active in the staging and production environments.
DetailedKeyCollection.production: Contains information about the key collection version that’s active in the production environment.
algorithm Enumeration The encryption algorithm of the public keys that the version uses in this environment to validate JWT signatures, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version.
startTime Integer An epoch timestamp marking when the key collection version was created.
DetailedKeyCollection.staging: Contains information about the key collection version that’s active in the staging environment.
algorithm Enumeration The encryption algorithm of the public keys that the version uses in this environment to validate JWT signatures, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version.
startTime Integer An epoch timestamp marking when the key collection version was created.
DetailedKeyCollection.versions[]: Contains information about a key collection version, including the type of public keys it uses to validate JWT signatures, and whether it’s active in the staging and production environments.
algorithm Enumeration The encryption algorithm of the public keys that the key collection version uses, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
collectionId Integer The identifier of the key collection associated with the key collection version.
createdBy String The username who created the key collection version.
createdDate Integer An epoch timestamp marking when the key collection version was created.
description String A description for the key collection version.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version. With each new version of this key collection, this number increments by 1.
productionStatus Enumeration The status of the key collection version in the production environment, either ACTIVE, INACTIVE, or PENDING.
stagingStatus Enumeration The status of the key collection version in the staging environment, either ACTIVE, INACTIVE, or PENDING.

Version

Contains information about a key collection version, including the type of public keys it uses to validate JWT signatures, and whether it’s active in the staging and production environments.

Download schema: keyCollectionVersionRS.json, pemPublicKeysRQ.json

Sample POST response:

{
    "id": 2,
    "collectionId": 12,
    "no": 1,
    "description": "A version active in the staging environment. ",
    "createdDate": 1522252256725,
    "createdBy": "keyAdministrator_EdgeConnect",
    "stagingStatus": "ACTIVE",
    "productionStatus": "INACTIVE",
    "algorithm": "ECDSA_P_256"
}

Version members

Member Type GET POST Description
Version: Contains information about a key collection version, including the type of public keys it uses to validate JWT signatures, and whether it’s active in the staging and production environments.
algorithm Enumeration The encryption algorithm of the public keys that the key collection version uses, either RSA or ECDSA_P_256. To see the public keys that the version uses, run the View a key collection version operation.
collectionId Integer The identifier of the key collection associated with the key collection version.
createdBy String The username who created the key collection version.
createdDate Integer An epoch timestamp marking when the key collection version was created.
description String A description for the key collection version.
id Integer The identifier of the key collection version.
no Integer The number of the key collection version. With each new version of this key collection, this number increments by 1.
primaryKey String The primary public key that you want to use to validate JWT signatures. You can use an RSA key that’s between 1024 and 4096 bits long, an ECDSA key that uses the P–256 (secp256k1) curve, or a server certificate to extract a public key from. Use a key or a certificate in PEM format, which presents base64-encoded data between the begin header and the end footer. Make sure to use the same encryption algorithm for the public keys in the primaryKey and secondaryKey members, either RSA or ECDSA_P_256. See Keys and JWT signing algorithms.
productionStatus Enumeration The status of the key collection version in the production environment, either ACTIVE, INACTIVE, or PENDING.
secondaryKey String The secondary public key that you want to use to validate JWT signatures in case primaryKey fails. You can use an RSA key that’s between 1024 and 4096 bits long, an ECDSA key that uses the P–256 (secp256k1) curve, or a server certificate to extract a public key from. Use a key or a certificate in PEM format, which presents base64-encoded data between the begin header and the end footer. Make sure to use the same encryption algorithm for the public keys in the primaryKey and secondaryKey members, either RSA or ECDSA_P_256. See Key rotation and Keys and JWT signing algorithms.
stagingStatus Enumeration The status of the key collection version in the staging environment, either ACTIVE, INACTIVE, or PENDING.

DetailedVersion

Contains detailed information about a key collection version, including its public keys and details about the encryption algorithm used for their generation. It also specifies whether the version is active in the staging and production environments.

Download schema: keyCollectionVersionDetailsRS.json

Sample GET response:

{
    "collectionId": 12,
    "versionId": 12,
    "versionNo": 1,
    "primaryKey": "-----BEGIN PUBLIC KEY-----\nsamplepublickey\n-----END PUBLIC KEY-----",
    "description": "The first version of the collection with a primary key for Edge Connect.",
    "staging": {
        "activatedBy": "keyAdministrator_EdgeConnect",
        "activatedOn": 1522748072292,
        "status": "ACTIVE"
    },
    "production": {
        "activatedBy": "keyAdministrator_EdgeConnect",
        "activatedOn": 1522748047092,
        "status": "ACTIVE"
    },
    "algorithm": "RSA",
    "algorithmDetails": "512 bits"
}

DetailedVersion members

Member Type Required Description
DetailedVersion: Contains detailed information about a key collection version, including its public keys and details about the encryption algorithm used for their generation. It also specifies whether the version is active in the staging and production environments.
algorithm Enumeration The encryption algorithm of the public keys in the primaryKey and secondaryKey members, either RSA or ECDSA_P_256.
algorithmDetails String Details about the encryption algorithm used to generate the public key in the primaryKey member. For RSA, it specifies the length of an RSA key. For ECDSA_P_256, it specifies the paraemter of the P–256 elliptic curve, only secp256k1 is available at this time. See Keys and JWT signing algorithms.
collectionId Integer The identifier of the key collection.
description String A description for the key collection version.
primaryKey String The primary RSA or ECDSA public key that the version uses to validate JWT signatures. It can also be the server certificate that the version uses to extract a public key from. This key or certificate is in PEM format, which presents base64-encoded data between the begin header and the end footer. See Keys and JWT signing algorithms.
production DetailedVersion.production Contains detailed information about the status of the key collection version in this environment.
secondaryAlgorithmDetails String Details about the encryption algorithm used to generate the public key in the secondaryKey member. For RSA, it specifies the length of the RSA key. For ECDSA_P_256, it specifies the parameter of the P–256 elliptic curve, only secp256k1 is available at this time. See Keys and JWT signing algorithms.
secondaryKey String The backup RSA or ECDSA public key that the version uses to validate JWT signatures in case the primaryKey fails. It can also be a server certificate that the version uses to extract a public key from. This key or certificate is in PEM format, which presents base64-encoded data between the begin header and the end footer. See Key rotation and Keys and JWT signing algorithms.
staging DetailedVersion.staging Contains detailed information about the status of the key collection version in this environment.
versionId Integer The identifier of the key collection version.
versionNo Integer The number of the key collection version. With each new version of this key collection, this number increments by 1.
DetailedVersion.production: Contains detailed information about the status of the key collection version in this environment.
activatedBy String The username who activated the key collection version.
activatedOn Integer An epoch timestamp marking when the activation was started.
status Enumeration The status of the key collection version in the environment. These values are available: ACTIVE, INACTIVE, or PENDING.
DetailedVersion.staging: Contains detailed information about the status of the key collection version in this environment.
activatedBy String The username who activated the key collection version.
activatedOn Integer An epoch timestamp marking when the activation was started.
status Enumeration The status of the key collection version in the environment. These values are available: ACTIVE, INACTIVE, or PENDING.

Activation

Contains detailed information about an activation of a key collection version, including the environment where you’re activating this version and the status of the activation.

Download schema: activationRS.json, activationRQ.json

Sample POST response:

{
    "id": 1,
    "environment": "PRODUCTION",
    "state": "DONE",
    "keyCollectionVersionId": 12,
    "keyCollectionVersionNo": 1,
    "startTime": 1522748047092,
    "activatedBy": "keyAdministrator_EdgeConnect"
}

Activation members

Member Type Required Description
Activation: Contains detailed information about an activation of a key collection version, including the environment where you’re activating this version and the status of the activation.
activatedBy String The username who sent the activation request.
environment Enumeration The environment where you’re activating the key collection version, either STAGING or PRODUCTION.
id Integer The identifier of the activation.
keyCollectionVersionId Integer The identifier of the key collection version that you’re activating.
keyCollectionVersionNo Integer The number of the version within the key collection. With each new version of this key collection, this number increments by 1.
startTime Integer An epoch timestamp marking when the activation was created.
state Enumeration The status of the activation across the platform. These values are available: PREPARED when the system is ready to propagate the activation, IN_PROGRESS when the system is already propagating the activation, DONE when the system has successfully propagated the activation, NOT_AVAILABLE when the system has been unable to access data for the activation, or ERROR when the system has failed to propagate the activation. To fix the ERROR and NOT_AVAILABLE states, send another activation request. If it fails, contact support.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

This API responds with HTTP Problem Details error objects. This sample shows an incorrect request error, where details explain why the error occurred and incidentId may be useful if you need to communicate about the problem with your support representative:

{
  "details": [
    {
      "code": "required.param.missing",
      "message": "Required parameter missing"
    }
  ],
  "code": "bad.request",
  "title": "Bad Request",
  "incidentId": "4fbffdcb-dd74-4d0d-9dfe-3b17fbdf66df"
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation succeeded.
201 Resource successfully created.
400 Bad Request.
401 API authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 No permission to access this resource. This most likely reflects a limitation on the identity of the Control Panel user corresponding to the API client. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found. This typically occurs when a resource keyed by a URL path parameter no longer exists, or if the request URL is garbled in some other way.
409 Something in the request data indicates a conflict with the current state of the resource.
500 Internal server error.