You are using a browser that is not supported.

Download API

How to Authenticate

Some products and releases may require authentication to access or modify.

We have introduced a new authentication workflow called the UAA API Token Workflow . This relies on the use of refresh and access tokens. Please see below for more information. The legacy tokens will be deprecated in the coming months.

Currently, your Edit Profile page contains the legacy API token as well as the new UAA API token.

UAA API Token Workflow

Definitions:

  • Access Token: This is a short-lived token that expires in an hour
  • UAA API Token (Refresh token): Currently, this token doesn’t expire. You can rotate this token periodically on your Edit Profile page.

Below are the steps you’d follow to authenticate with the new workflow:

  1. Retrieve a UAA API Token (refresh token) from your Pivnet profile;
  2. Use your UAA API Token to retrieve access tokens using the below POST method;
  3. Use your access token to authenticate against the Pivnet API using the GET method.

Request Headers

HEADER          VALUE
------          -----
Accept:         application/json
Content-Type:   application/json
Authorization:  Bearer <Access Token>

Example cURL request

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <Access Token>" -X GET https://network.pivotal.io/api/v2/authentication

Legacy API Token Workflow

Below are the steps you’d follow to authenticate with the new workflow:

  1. Retrieve a Legacy Token from your Pivnet profile;
  2. Use your legacy token to authenticate against the Pivnet API using the GET method.

Request Headers, Legacy Tokens

HEADER          VALUE
------          -----
Accept:         application/json
Content-Type:   application/json
Authorization:  Token <Legacy API Token>

Example cURL request

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token <Legacy API Token>" -X GET https://network.pivotal.io/api/v2/authentication

POST /api/v2/authentication/access_tokens

Note: This method would work only for the new UAA API Token.

  • Exchanges a UAA refresh token for a temporary UAA access token.
    • returns 200 if successful
    • returns 401 if UAA rejects the refresh token
    • returns 500 if UAA is unavailable
  • Access tokens expire in 1 hour

Example

Request

POST /api/v2/authentication/access_tokens HTTP/1.1
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Length: 26
Content-Type: application/x-www-form-urlencoded
Host: www.example.com


{"refresh_token":"abc123"}

Response

HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 25
Content-Type: application/json; charset=utf-8
ETag: W/"dcd9e9446ed27172c3eff227246daeef"
Vary: Accept-Encoding


{
  "access_token": "xyz890"
}

GET /api/v2/authentication

Tests that your authorization token is valid (UAA API Token Workflow)

  • returns 200 if successful
  • returns 401 if user could not be authenticated

Note: This example explains the UAA API Token Workflow. If you’re looking to use the legacy token workflow, please replace “Bearer” with “Token” in the Authorization parameter of the Request Header.

Example

Request

GET /api/v2/authentication HTTP/1.1
Accept: application/json
Authorization: Bearer access-token
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 200
Cache-Control: no-cache
Content-Length: 0
Content-Type: application/json
Vary: Accept-Encoding

Get Product ID via GET /api/v2/products

  • Returns a list of products
    • returns 200 if successful
    • returns 401 if user could not be authenticated
  • Authentication optional, but required to view products not publicly available

Example

Request

GET /api/v2/products HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 1080
Content-Type: application/json; charset=utf-8
ETag: W/"c1c21bd6c3077d89c5d16d0d8e03922e"


{
  "products": [
    {
      "id": 454,
      "slug": "product-16",
      "name": "Product 21",
      "logo_url": "http://localhost/cloud_front_stub/assets/images/p-logo.png",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-16"
        },
        "releases": {
          "href": "https://network.pivotal.io/api/v2/products/product-16/releases"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-16/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-16/file_groups"
        }
      }
    },
    {
      "id": 455,
      "slug": "product-17",
      "name": "Product 22",
      "logo_url": "http://localhost/cloud_front_stub/assets/images/p-logo.png",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-17"
        },
        "releases": {
          "href": "https://network.pivotal.io/api/v2/products/product-17/releases"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-17/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-17/file_groups"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products"
    }
  }
}

Get Release ID via GET /api/v2/products/:product_slug/releases

  • Lists releases associated with the specified product
    • returns 200 if the releases are found
    • returns 401 if user could not be authenticated
    • returns 404 if the product cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request

GET /api/v2/products/product-29/releases HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-20"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 3937
Content-Type: application/json; charset=utf-8
ETag: W/"2f770741f9b00f73cdb6df74e1dabc99"


{
  "releases": [
    {
      "id": 292,
      "version": "1.2.alpha",
      "release_type": "Minor Release",
      "release_date": "2015-06-16",
      "release_notes_url": "http://example.com/release",
      "availability": "Admins Only",
      "description": "Release description",
      "eula": {
        "id": 258,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/258"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
 "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/292"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/292/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/292/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/292/user_groups"
        }
      }
    },
    {
      "id": 291,
      "version": "2.0.beta1",
      "release_type": "Major Release",
      "release_date": "2015-06-16",
      "release_notes_url": "http://example.com/release",
      "availability": "Selected User Groups Only",
      "description": "Release description",
      "eula": {
        "id": 258,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/258"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/291"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/291/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/291/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/291/user_groups"
        }
      }
    },
    {
      "id": 290,
      "version": "1.1",
      "release_type": "Minor Release",
      "release_date": "2015-06-16",
      "release_notes_url": "http://example.net/release-notes1",
      "availability": "All Users",
      "description": "Interesting release facts",
      "eula": {
        "id": 258,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/258"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/290"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/290/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/290/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/290/user_groups"
        }
      }
    },
    {
      "id": 289,
      "version": "1.0",
      "release_type": "Major Release",
      "release_date": "2015-06-16",
      "release_notes_url": "http://example.com/release",
      "availability": "All Users",
      "description": "Release description",
      "eula": {
        "id": 258,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/258"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/289"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/289/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/289/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-29/releases/289/user_groups"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-29/releases"
    }
  }
}

Get File ID via GET /api/v2/products/:product_slug/releases/:id

  • Returns a specific release associated with the specified product
    • returns 200 if the release is found
    • returns 401 if user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request

GET /api/v2/products/product-30/releases/293 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-21"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 1759
Content-Type: application/json; charset=utf-8
ETag: W/"5a4b73ce14dd3d282a2facc728bfb146"


{
  "id": 293,
  "version": "1.1.1.1",
  "release_type": "Major Release",
  "release_date": "2015-06-16",
  "release_notes_url": "http://example.com/release",
  "availability": "All Users",
  "description": "Release description",
  "eula": {
    "id": 259,
    "slug": "pivotal_software_eula",
    "name": "Pivotal Software EULA",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/eulas/259"
      }
    }
  },
  "end_of_support_date": "2015-05-10",
  "end_of_guidance_date": "2015-06-30",
  "end_of_availability_date": "2015-07-04",
  "eccn": "5D002",
  "license_exception": "ENC Unrestricted",
 "product_files": [
    {
      "id": 249,
      "aws_object_key": "product_files_test/file.txt",
      "file_version": "1.0.0",
      "name": "Product File 18",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/product_files/249"
        },
        "download": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/product_files/249/download"
        }
    }
  ],
  "file_groups": [
    {
      "id": 48,
      "name": "File Group 10",
      "product_files": [
        {
          "id": 249,
          "aws_object_key": "product_files_test/file.txt",
          "file_version": "1.0.0",
      "name": "Product File 18",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/product_files/249"
            },
            "download": {
              "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/product_files/249/download"
            }
        }
      ],
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/file_groups/48"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293"
    },
    "product_files": {
      "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/product_files"
    },
    "file_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/file_groups"
    },
    "user_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-30/releases/293/user_groups"
    }
  }
}

Accept EULA via POST /api/v2/products/:product_slug/releases/:release_id/eula_acceptance

  • Accept a release's End User License Agreement (EULA).
    • returns 200 if the EULA is accepted
    • returns 401 if the user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Authentication required

Example

Request

POST /api/v2/products/458/releases/278/eula_acceptance HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-8"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 101
Content-Type: application/json; charset=utf-8
ETag: W/"3c42024da70ce09a46efe6f5d7536744"


{
  "accepted_at": "2015-06-16",
  "_links": {
    "eula": {
      "href": "https://network.pivotal.io/api/v2/eulas/247"
    }
  }
}

Download File via GET /api/v2/products/:product_slug/releases/:release_id/product_files/:id/download

  • Creates a download link for a release's product file. The user can utilize this link to download the file.
    • redirects to a unique file download URL
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to download files from this release
    • returns 404 if the product or release cannot be found
    • returns 451 if user has not accepted the current EULA for this release
  • Authentication required

Example wget request

wget -O "<filename>" --header="Authorization: Token <API Token>" https://network.pivotal.io/api/v2/products/<product-id>/releases/<release-id>/product_files/<product-file-id>/download

Example

Request

GET /api/v2/products/product-3/releases/259/product_files/226/download HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-1"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response

HTTP/1.1 302
Cache-Control: no-cache
Content-Length: 127
Content-Type: text/html; charset=utf-8
Location: http://localhost/cloud_front_stub/product_files_test/file.txt


<html><body>You are being <a href="http://localhost/cloud_front_stub/product_files_test/file.txt">redirected</a>.</body></html>