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 apps. You can create a token for an installed app and assign it to a managed server to securely connect to CloudBees SDM APIs. This allows servers to ingest data and securely push data to CloudBees SDM.

The following types of tokens are supported
  1. Refresh token - a long-lived token used to securely fetch a short-lived access token which can be used to connect to the CloudBees SDM API.

  2. Personal access token - a long-lived authentication token that can be used to access the CloudBees SDM API via a script or application. 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 accounts 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.

Refresh tokens

A 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 a refresh token for a specific app that needs to access data in CloudBees SDM. This app uses this refresh 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, at which point you will need to use its associated refresh token to generate a new short-lived app access token.

Generating refresh tokens

You need to generate a refresh token for each app. The following example shows the steps to generate a 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 refresh token now. You will not be able to see it again.

  6. Select Finish.

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

To generate an app access token from the command line:

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

  2. Set the 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 a refresh token:

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

Revoking refresh tokens

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

To revoke a 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 refresh token is no longer available and can not be used. The access token generation will fail if the 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 account 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 refresh and personal 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 account 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.