Create and use tokens with the Chef 360 Platform APIs

Chef 360 Platform supports the following methods of authorization when calling its APIs:

API access key and secret key (recommended)
JSON Web Token (JWT)

API access key and secret key

Since the lifespan of an API secret key and access key is under your control, we recommend this approach for any long-term interactions with a Chef 360 Platform API, for example, in CI/CD pipelines.

You can create a new set of access keys using the chef-platform-auth-cli CLI or use the access keys returned by Chef 360 Platform when you first register your workstation with Chef 360 Platform. We recommend creating a new pair.

Before you begin

Before you can create a set of access keys, enable this method of authentication in the Chef 360 Platform configuration:

In the Chef 360 Platform API/UI settings, select the Enable authentication by API token checkbox.

Create a new API access key and secret key

To create a new pair of API keys, follow this step:

Generate a new token with the create-token command:

chef-platform-auth-cli user-account self create-token \
--body '{"expiration": "<EXPIRATION_DATE>","name": "<TOKEN_NAME>"}' \
--profile <PROFILE_NAME>

Replace:

<EXPIRATION_DATE> with the date and time in ISO 8601 format. For example, 2029-12-31T11:42:23-05:00.
<TOKEN_NAME> with a name for the token that’s unique in the organizational unit.
<PROFILE_NAME> with a profile. The token will have the same access rights as the profile you use. Use the principle of least privilege (PoLP) to give the token only the privileges that it needs.

The response is similar to the following:

{
    "item": {
        "accessKey": "DF5CIL9OOTSL4WEJLUYW",
        "expiration": "2029-12-31T11:42:23-05:00",
        "id": "95b4d947-712b-4b87-96b5-339d33505469",
        "name": "CI/CD token",
        "role": {
            "id": "5fcb0235-1e56-4ece-8857-404a5d39a290",
            "name": "courier-operator"
        },
        "secretKey": "w2iasWrRVwbREaQOzAOW2t28blqf5kN3oMpCEfhm"
    }
}

Save the access key and secret key along with the token details.

Get access key and secret key during registration

Chef 360 Platform returns API access keys when you first register your workstation. You can use these keys; however, we recommend creating new ones.

Use the access key and secret key

Once you have the access key and secret, add them to the headers when making an API call. For example:

curl -k -X GET <TENANT_URL>/courier/scheduler-api/v1/jobs \
-H "Content-Type: application/json" \
-H "api-key: <API_ACCESS_KEY>" \
-H "api-secret: <API_SECRET_KEY>"

JSON Web Token (JWT)

JSON Web Tokens (JWT) are designed to expire within a very short period of time and aren’t recommended for long-term API integrations.

Before you begin

You’ll need an access key and secret key to create a JSON Web Token.

Get an access token

Get an OAuth code with the user-accounts API:

curl -k -X POST <TENANT_URL>/platform/user-accounts/v1/user/api-token/login \
     -H "Content-Type: application/json" \
     -d '{"accessKey": "<ACCESS_KEY>", "secretKey": "<SECRET_KEY>", "state": "<STATE>"}'

This returns an OAuth code.

Get an access token using the OAuth code and the user-accounts API:

curl -k -X POST <TENANT_URL>/platform/user-accounts/v1/user/api-token/jwt \
     -H "Content-Type: application/json" \
     -d '{"oauthCode": "<OAUTH_CODE>", "state": "<STATE>"}'

The response includes an access token and expiration in Unix time format.

Use the JSON Web Token

You can then use the access token in the headers of API calls. For example:

curl -k -X GET <TENANT_URL>/courier/scheduler-api/v1/jobs \
-H "Content-Type: application/json" \
--header 'Authorization: Bearer <JSON_WEB_TOKEN>'