Authenticating apps

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support. Learn more about the preview program.

Tokens are used to authenticate access to CloudBees APIs. Administrators and users can provision tokens that will grant servers access to the CloudBees SDM APIs.

The following types of tokens are supported
App refresh token

These tokens are used by customer-managed servers such as Jenkins that connect to CloudBees SDM as part of a data integration app. These long-lived tokens are used to securely fetch a short-lived access token which can be used to connect to the CloudBees SDM API.

Personal access token

You can use these tokens to connect to the CloudBees SDM API based on the user identity that the token was provisioned with. These tokens are long-lived and should be used as an Authorization header in the HTTP request.

Tokens can use the following API calls
GET /platform/api/app/installations

List the user profiles that the application has been installed in.

DELETE /platform/api/app/installations/{account}

Uninstall an account from the application.

POST /platform/api/app/installations/{account}/accessToken

Exchange the application issued JWT for a Platform issued JWT that is valid for use against peer services as the specified account.

POST /platform/api/app/{appId}/installations/{account}/token

Provision a long-lived refresh token that can be used to retrieve an access token for an installation of the app in an account.

GET /platform/api/app/{appId}/installations/{account}/token

List the refresh tokens for an installation of the app in an account.

DELETE /platform/api/app/{appId}/installations/{account}/token/{tokenId}

Revoke a long-lived refresh token.

POST /platform/api/app/accessToken

Exchange the application issued JSON web token (JWT) for a platform-issued JWT that is valid for use against peer services as the app itself.

App refresh tokens

An app refresh token is a long-lived token used to securely fetch a short-lived access token which can be used to connect to the CloudBees SDM API. For example, you can generate an app refresh token for a specific app that needs to access data in CloudBees SDM. This app uses this token to fetch a short-lived app access token which is used to authenticate when pushing data into CloudBees SDM. Short-lived app access tokens expire after 1 hour. Using an expired app access token results in a 401 (Unauthorized) HTTP response. To correct this error, you will need to use its associated app refresh token to generate a new short-lived app access token.

Generating app refresh tokens

You need to generate an app refresh token for each app. The following example shows the steps to generate an app refresh token in the CloudBees SDM UI for the Jenkins X app:

  1. Select Apps.

  2. Select Jenkins X, and then select Security tokens.

  3. Select Create a refresh token for the Jenkins X App.

  4. Enter a name for the refresh token.

  5. Select Create token. IMPORTANT: Copy the app refresh token now. You will not see it again.

  6. Select Finish.

Next, capture the app refresh token and store it securely in a place where your app will have access to it. An app refresh token has the following format: R.12345678-abcd-efgh-1234-1234567890ab. R.12345678-abcd-efgh-1234-1234567890ab is an example token.

Your app’s remote client exchanges the app refresh token for a short-lived access token. The following shows the steps of the exchange:

  1. Make a POST request to /platform/api/app/installations/{account}/accessToken.

  2. Set the app refresh token as a bearer token in an Authorization header in your HTTP request. The format in the HTTP request is Authorization: Bearer <refresh-token>.

  3. The response for the POST request includes the short-lived app access token.

The following curl example shows how to generate an app access token using an app refresh token:

curl https://devoptics.cloudbees.com/platform/api/app/installations/{account}/accessToken -H "Authorization: bearer R.12345678-abcd-efgh-1234-1234567890ab"

Revoking app refresh tokens

App refresh tokens do not expire. You can revoke the app refresh token to deactivate it and remove it from CloudBees SDM. This removes the authentication mechanism for any apps using the token.

To revoke an app refresh token for Jenkins X:

  1. Select Apps.

  2. Select Jenkins X, and then select Security tokens.

  3. Select the token that you would like to revoke.

  4. Select Revoke at the far right.

  5. Select Revoke.

The app refresh token is no longer available and can not be used. The access token generation will fail if the app refresh token has been revoked.

Personal access tokens

A personal access token is a long-lived token that can be used by scripts and applications to make authenticated requests on behalf of a user. For example, you could use a personal access token in an Authorization header in the HTTP request to authenticate a request.

Generating personal access tokens

To generate a personal access token in the CloudBees SDM UI:

  1. Select your user profile on the top right.

  2. In the drop-down menu, select Personal access tokens.

  3. Select Create a token.

  4. Enter a name for the personal access token.

  5. Select Create token.

  6. Copy the refresh token now. You will not be able to see it again.

A personal access token has the following format: U.12345678-abcd-efgh-1234-1234567890ab. U.12345678-abcd-efgh-1234-1234567890ab is an example token. See Making API calls with access tokens for an example of generating a personal access token from the command line.

Revoking personal access tokens

Personal access tokens do not expire. You can revoke the personal access token to deactivate it and remove it from CloudBees SDM. Once removed, the token cannot be used to access the CloudBees SDM APIs.

To revoke a personal access token:

  1. From within CloudBees SDM, select your user profile on the top right.

  2. In the drop down menu, select Personal access tokens.

  3. View the list of tokens, choose the token that you would like to revoke and select Revoke token.

  4. Select Revoke token.

The revoked personal access is no longer valid and can not be used.

Making API calls with access tokens

You use access tokens to make API calls on behalf of the app. Once you create the token, you can set it as a bearer token in the Authentication header in the HTTP request.

The following example shows a GraphQL request on the System of Record that is authenticated using a personal access token:

curl https://app.cloudbees.com/data/api/v1/a/cloudbees/graphql   -H 'content-type: application/json'   --data-binary '{"query":"{products(first: 5) {totalCount nodes {name} }}"}' -H 'Authorization: Bearer U.2473d6b3-c0e2-1212-bd12-123123123123'

A successful response returns:

{
  "data": {
    "products": {
      "totalCount": 38,
      "nodes": [
        {
          "name": "Product 1"
        },
        {
          "name": "Product 2"
        },
        {
          "name": "Product 3"
        },
        {
          "name": "Product 4"
        },
        {
          "name": "Product 5"
        }
      ]
    }
  }
}

If no response, check if your token is correct.