Create or Modify an Asset

To use our API, you need a Cobalt account with membership in your organization. Your organization owner can create an account and assign you as a member. Your organization owner is typically the user who interacts with the Cobalt Customer Success Manager (CSM).

You can create an asset in the UI. If you prefer to automate the process and/or work from the command line, you can also use our API.

To create or modify an asset with our API, follow the sequence of commands shown on this page.

Create an API Token in the Cobalt UI

1. Navigate to https://app.cobalt.io/settings/api-tokens.
2. If needed, sign in to the app.
3. Enter an API Token Name.
4. Select Generate New Token.
5. In the modal that appears, you should see your API Token, in the Secret Token text box.

Save the API Token. After you close the overlay, you won’t see the full token again. If you lose it, you may have to revoke the token and start over.

Substitute the API token for YOUR-PERSONAL-API-TOKEN in the REST calls described on this page.

Use the API Token to Authorize Access

Next, you can use the API Token to authorize access to the Cobalt API. Take the API Token that you generated. Substitute that value for YOUR-PERSONAL-API-TOKEN:

curl https://api.cobalt.io/orgs \
     -H "Accept: application/vnd.cobalt.v2+json" \
     -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
     | jq .

{
  "pagination": {
    "next_page": null,
    "prev_page": null
  },
  "data": [
    {
      "resource": {
        "id": "some_id",
        "name": "Name of your organization",
        "token": "YOUR-V2-ORGANIZATION-TOKEN"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/not_a_jwt_token"
        }
      }
    }
  ]
}

From the output, save the value for token as your organization token. In our API documentation, you’ll see this as YOUR-V2-ORGANIZATION-TOKEN.

For more information, see our API reference documentation on the organizations orgs endpoint.

Create an Asset

Now that you have the following information:

• YOUR-PERSONAL-API-TOKEN
• YOUR-V2-ORGANIZATION-TOKEN

You can create an asset with the following REST call:

curl -X POST "https://api.cobalt.io/assets" \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: application/vnd.cobalt.v2+json' \
  -H 'Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN' \
  --data '{
            "title": "Test Asset",
            "description": "How to describe the asset to our pentesters",
            "asset_type": "web"
          }' \
  -v

For more information on each parameter, see our API reference documentation on how to Create an Asset.

The command we use includes a -v, which sets up output in verbose mode. The command works without it. However, you would see no response from this REST call.

When you review the output of the REST call with the -v, look for the line with HTTP/2. If the command is successful, you’ll see

For a list of error codes, see the Errors section of our API reference.

Next Steps

Once you create an asset, you can:

• Continue with our API. You can Find Your Asset ID and then Add or Modify Asset Details.
• Sign in to our UI and modify details of your newly created asset.

Find Your Asset ID

To add or modify information related to your asset, you’ll need the asset ID. You can find this ID with the REST call to Get All Assets:

curl -X GET "https://api.cobalt.io/assets" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \
  | jq .

If you’ve set up more than one asset, you may need to search through the output. You can also limit the number of assets in the output with the limit parameter. For more information about each asset response field, see our API reference to Get All Assets.

{
  "data": {
    "resource": {
      "id": "YOUR-ASSET-IDENTIFIER",
      "title": "Test Asset",
      "description": "How to describe the asset to our pentesters",
      "asset_type": "web",
      "logo": null,
      "attachments": []
    },
    "links": {
      "ui": {
        "url": "https://api.cobalt.io/links/<endpoint for the asset>"
      }
    }
  }
}

If you’ve set up more than one asset, you’ll see the id in the same object as the title, which you may have used to create the asset.

Save the value of the asset id as YOUR-ASSET-IDENTIFIER. You’ll use that ID, which starts with as_, when updating or uploading information to your asset.

Add or Modify Asset Details

Now that you’ve created an asset and have the asset ID, you can add more information with the following REST call:

curl -X PUT 'https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: application/vnd.cobalt.v2+json' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN' \
  --data '{
            "title": "Updated title",
            "description": "Updated description",
            "asset_type": "web"
          }' \
  -v

When you review the output of the REST call with the -v, look for the line with HTTP/2. If the command is successful, you’ll see:

For a list of error codes, see the Errors section of our API reference.