NAV Navbar
Logo
shell

Introduction

CredHub manages credentials like passwords, users, certificates, certificate authorities, ssh keys, rsa keys and arbitrary values (strings and JSON blobs). The following spec details the API exposed by the CredHub server and the equivalent requests using the CredHub CLI.

More information on CredHub can be found here.

Credential Naming and Paths

Credentials can be named with any value up to 255 characters containing alpha, numeric, underscore _, hyphen -, forward slash /, period ., colon :, parenthesis ( ), and bracket [ ] characters. The character limit includes the leading slash, which will be prepended automatically if absent.

Paths can be used to namespace a set of credential names for a different deployment or environment. To add a path to a credential, simply add the path prior to the credential name, separated by a forward slash (/), e.g. credhub set -t password -n /prod/deploy123/cc_password -v 'value'. If a leading slash is not provided, it will be automatically prepended.

Credential IDs

Credential responses include a unique identifier in the key ‘id’. This ID is a unique identifier for a specific credential version. When a credential value is updated, a new ID will be returned. This identifier can be useful in applications where a specific credential value should be pinned until a manual action (such as a deployment) is performed. If your application should receive the latest value of the credential, retrieving by name is preferred.

Overwriting Credential Values

In the latest 2.0.x, set requests always overwrite the credential that already exists.

In the latest 2.0.x, generate requests can be set to overwrite, no-overwrite, or converge for the mode parameter. The default mode for generate is converge as of 2.0.0. Converge will only overwrite if the generate request parameters do not match the existing credential.

Authentication

All requests to CredHub, with the exception of /info and /health, must include an authentication method. CredHub supports two authentication provider types, UAA and mutual TLS.

UAA (oAuth2)

CredHub CLI

user$ credhub login --server example.com

cURL

curl "https://example.com/info" \
  -X GET \
  -H 'content-type: application/json'
{
  "auth-server": {
    "url": "https://uaa.example.com:8443"
  },
  "app": {
    "name": "CredHub"
  }
}

Authentication via UAA is performed directly with the trusted UAA server. When successfully authenticated, the UAA server will return an access token, which must be sent to CredHub in each request.

The address of the UAA server trusted by the targeted CredHub server can be obtained by requesting the /info endpoint. With that endpoint, you may send a token request as detailed here.

Once you have obtained a token, you must include the token value in the header authorization: bearer [token] in your request to CredHub.

Mutual TLS

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/data?name=/example-password" \
  -X GET \
  -H 'content-type: application/json' \
  --cert certificate.pem \
  --key private_key.pem
{
  "data": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-password",
      "type": "password",
      "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
      "version_created_at": "2017-01-05T01:01:01Z"
    }
  ]
}

CredHub supports mutual TLS authentication. Certificates issued by trusted Certificate Authorities are accepted by CredHub. To provide an authenticated identity in the client mtls certificate, CredHub requires the Organization Unit of the certificate to comply with the pattern app:<v4 UUId>. CredHub validates the authenticated identity, signing authority, validity dates and presence of x509 extension Extended Key Usage ‘Client Authentication’ during the authentication workflow.

Credentials

Credentials are the primary object in CredHub. Any passwords, secrets, configurations or other sensitive information that you store is saved to a named credential. You can retrieve, update and delete a credential using its name.

All credentials, regardless of type, share a common namespace, e.g. a credential named /diego-tls exists once in CredHub. Credential names are not reservable, so two users updating a credential of the same name will result in updates to the same credential. If you prefer a separate namespace for your credentials, you can add a path prior to the credential name.

Credentials are typed based on the format of the stored value, value validation and generation procedure. Once a credential type has been set, it cannot be updated to a new type. If you mistakenly set the type, you must delete the credential, then set it with the correct type.

Get Credentials

Get by ID

CredHub CLI

user$ credhub get --id 2993f622-cb1e-4e00-a267-4b23c273bf3d
id: 2993f622-cb1e-4e00-a267-4b23c273bf3d
name: /example-password
type: password
value: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
version_created_at: 2017-01-05T01:01:01Z

cURL

curl "https://example.com/api/v1/data/2993f622-cb1e-4e00-a267-4b23c273bf3d" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "password",
  "version_created_at": "2017-01-05T01:01:01Z",
  "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d",
  "name": "/example-password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
}

This request retrieves a credential by ID. Exactly one value will be returned.

HTTP Request

GET: https://example.com/api/v1/data/[Credential-ID]

Query Parameters

Parameter Default Required Type Description
none

Get by Name

CredHub CLI

user$ credhub get --name '/example-password'
id: 2993f622-cb1e-4e00-a267-4b23c273bf3d
name: /example-password
type: password
value: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
version_created_at: 2017-01-05T01:01:01Z

cURL

curl "https://example.com/api/v1/data?name=/example-password" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "password",
      "version_created_at": "2017-01-05T01:01:01Z",
      "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d",
      "name": "/example-password",
      "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
    },
    {
      "type": "password",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad674",
      "name": "/example-password",
      "value": "3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R"
    }
  ]
}

This request returns a credential’s value(s) by name. All historical values will be returned unless "current": true or "versions": # is specified.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: Value

CredHub CLI

user$ credhub get --name '/example-value'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-value" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "value",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-value",
      "value": "sample"
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of a value type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: JSON

CredHub CLI

user$ credhub get --name '/example-json'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-json
type: json
value:
  key: 123
  key_list:
  - val1
  - val2
  is_true: true
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-json" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "json",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-json",
      "value": {
        "key": 123,
        "key_list": [
          "val1",
          "val2"
        ],
        "is_true": true
      }
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of a JSON type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: Password

CredHub CLI

user$ credhub get --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-password" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "password",
      "version_created_at": "2017-01-05T01:01:01Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-password",
      "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of a password type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: User

CredHub CLI

user$ credhub get --name '/example-user'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
  username: FQnwWoxgSrDuqDLmeLpU
  password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
  password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-user" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "user",
      "version_created_at": "2017-01-05T01:01:01Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-user",
      "value": {
        "username": "FQnwWoxgSrDuqDLmeLpU",
        "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
        "password_hash": "$6$uu8ybZiNiPRu$6AYClxVqMXA3LAIdDAnEuWLUlWGlm0RRJI2wdHd8R9hKkKtiYupyKBjdRBI1ZhsyHwYetCpySew9ZXXLf.Mih0"
      }
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of a user type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: Certificate

CredHub CLI

user$ credhub get --name '/example-certificate'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
  root: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-certificate" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "certificate",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
      "name": "/example-certificate",
      "value": {
        "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of a certificate type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Returns latest credential version and transitional version, if one exists
versions none no integer Return latest N credential versions

Type: RSA

CredHub CLI

user$ credhub get --name '/example-rsa'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
  public_key: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-rsa" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "rsa",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
      "name": "/example-rsa",
      "value": {
        "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of an RSA type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Type: SSH

CredHub CLI

user$ credhub get --name '/example-ssh'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
  public_key: ssh-rsa AAAAB3Nz...
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data?name=/example-ssh" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "data": [
    {
      "type": "ssh",
      "version_created_at": "2017-01-01T04:07:18Z",
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad678",
      "name": "/example-ssh",
      "value": {
        "public_key": "ssh-rsa AAAAB3Nz...",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
        "public_key_fingerprint": "EvI0/GIUgDjcoCzUQM+EtwnVTryNsKRd6TrHAGKJJSI"
      }
    }
  ]
}

This request returns a credential by name. The example provided shows the request parameters and response structure of an SSH type credential.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve
current false no string Return only latest credential version
versions none no integer Return latest N credential versions

Bulk Export

CredHub CLI

user$ credhub export --file export.yml

Sample Export File

credentials:
- name: /example-ssh
  type: ssh
  value:
    public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
- name: /example-password
  type: password
  value: SqFcE2c0AuRvet2YhrxdFbPtkBmjiq
- name: /example-value
  type: value
  value: sample

This CLI command gets multiple credentials and exports them to either standard out, or a file. The output will be in yaml format, with the key credentials whose value is a list of credential objects. Each credential will contain a name, type and value. An example is shown to the right. This file is compatible with the bulk import process.

Use --file to specify a file to write the export to. Use --path to specify a path, which will restrict the credentials exported to those with a prefix matching the given path.

HTTP Request

n/a

Request Parameters

Parameter Default Required Type Description
n/a

Set Credentials

Type: Value

CredHub CLI

user$ credhub set --type value --name '/example-value' --password 'sample'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-value",
      "type": "value",
      "value": "sample"
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "value",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-value",
  "value": "sample"
}

This request sets a value credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes string Value of credential to set

Type: JSON

CredHub CLI

user$ credhub set --type json --name '/example-json' --value '{ "key": 123, "key_list": ["val1","val2"], "is_true": true }'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-json
type: json
value:
  key: 123
  key_list:
  - val1
  - val2
  is_true: true
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-json",
      "type": "json",
      "value": {
        "key": 123,
        "key_list": [
          "val1",
          "val2"
        ],
        "is_true": true
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "json",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-json",
  "value": {
    "key": 123,
    "key_list": [
      "val1",
      "val2"
    ],
    "is_true": true
  }
}

This request sets a json credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes object Value of credential to set

Type: Password

CredHub CLI

user$ credhub set --type password --name '/example-password' --password '3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-password",
      "type": "password",
      "value": "3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R"
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "password",
  "version_created_at": "2017-01-05T01:01:01Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
}

This request sets a password credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes string Value of credential to set

Type: User

CredHub CLI

user$ credhub set --type user --name '/example-user' --username 'FQnwWoxgSrDuqDLmeLpU' --password '6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
  username: FQnwWoxgSrDuqDLmeLpU
  password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
  password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-user",
      "type": "user",
      "value": {
        "username": "FQnwWoxgSrDuqDLmeLpU",
        "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "user",
  "version_created_at": "2017-01-05T01:01:01Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-user",
  "value": {
    "username": "FQnwWoxgSrDuqDLmeLpU",
    "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
    "password_hash": "$6$uu8ybZiNiPRu$6AYClxVqMXA3LAIdDAnEuWLUlWGlm0RRJI2wdHd8R9hKkKtiYupyKBjdRBI1ZhsyHwYetCpySew9ZXXLf.Mih0"
  }
}

This request sets a user credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes object
value.username null no string Username value of credential to set
value.password none yes string Password value of credential to set

Type: Certificate

CredHub CLI

user$ credhub set --type certificate --name '/example-certificate' --root ./root.pem --certificate ./cert.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
  root: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-certificate",
      "type": "certificate",
      "value": {
        "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "certificate",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "name": "/example-certificate",
  "value": {
    "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request sets a certificate credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes object
value.ca null no1,2 string Certificate authority value of credential to set
value.ca_name null no2 string Name of CA credential in credhub that has signed this certificate
value.certificate null no1 string Certificate value of credential to set
value.private_key null no1 string Private key value of credential to set

1 At least one value must be set
2 ‘ca_name’ and ‘ca’ are mutually exclusive values

Type: RSA

CredHub CLI

user$ credhub set --type rsa --name '/example-rsa' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
  public_key: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-rsa",
      "type": "rsa",
      "value": {
        "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "rsa",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "name": "/example-rsa",
  "value": {
    "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request sets a RSA credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes object
value.public_key null no1 string Public key value of credential to set
value.private_key null no1 string Private key value of credential to set

1 At least one value must be set

Type: SSH

CredHub CLI

user$ credhub set --type ssh --name '/example-ssh' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
  public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X PUT \
  -d '{
      "name": "/example-ssh",
      "type": "ssh",
      "value": {
        "public_key": "ssh-rsa AAAAB3NzaC1y...W9RWFM1",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "ssh",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "name": "/example-ssh",
  "value": {
    "public_key": "ssh-rsa AAAAB3NzaC1y...W9RWFM1",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request sets a SSH credential with a user-provided value.

HTTP Request

PUT: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
value none yes object
value.public_key null no1 string Public key value of credential to set
value.private_key null no1 string Private key value of credential to set

1 At least one value must be set

Bulk Import

CredHub CLI

user$ credhub import --file import.yml
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
  public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

id: 2ba73fbd-439e-40ef-b005-0e1db8815063
name: /example-password
type: password
value: SqFcE2c0AuRvet2YhrxdFbPtkBmjiq
version_created_at: 2017-01-01T04:07:28Z

id: 22a1e87b-ba0b-4bc9-bb26-4e5fc5fb1b2f
name: /example-value
type: value
value: sample
version_created_at: 2017-01-01T04:07:38Z

Import complete.
Successfully set: 3
Failed to set: 0

Sample Import File

credentials:
- name: /example-ssh
  type: ssh
  value:
    public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
- name: /example-password
  type: password
  value: SqFcE2c0AuRvet2YhrxdFbPtkBmjiq
- name: /example-value
  type: value
  value: sample

This CLI command sets multiple credentials from an import file. The import file must be in yaml format, with the key credentials whose value is a list of credential objects. Each credential must contain a name, type and value. An example is shown to the right.

HTTP Request

n/a

Request Parameters

Parameter Default Required Type Description
n/a

Generate Credentials

Type: Password

CredHub CLI

user$ credhub generate --type password --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X POST \
  -d '{
      "name": "/example-password",
      "type": "password",
      "parameters": {
        "length": 40
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "password",
  "version_created_at": "2017-01-05T01:01:01Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
}

This request generates a password credential based on the provided parameters.

HTTP Request

POST: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
mode converge no enum1 Overwrite interaction mode
parameters none no object Generation parameters
parameters.length 30 no integer Length of generated credential value
parameters.exclude_upper false no boolean Exclude upper alpha characters from generated credential value
parameters.exclude_lower false no boolean Exclude lower alpha characters from generated credential value
parameters.exclude_number false no boolean Exclude number characters from generated credential value
parameters.include_special false no boolean Include special characters from generated credential value

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.

Type: User

CredHub CLI

user$ credhub generate --type user --name '/example-user'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-user
type: user
value:
  username: FQnwWoxgSrDuqDLmeLpU
  password: 6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL
  password_hash: $6$h3b3JsG5$MnrPIrF6T3zAWk9uaun64vWY.vaBQ5nTRFZjjVqKuDWccxWXn8n6vstQykXEReamb4GYh2q1HC7vFy11wflXd0
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X POST \
  -d '{
      "name": "/example-user",
      "type": "user"
      "parameters": {
        "length": 40
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "user",
  "version_created_at": "2017-01-05T01:01:01Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-user",
  "value": {
    "username": "FQnwWoxgSrDuqDLmeLpU",
    "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
  }
}

This request generates a user credential based on the provided parameters.

NOTE: The username value is accepted at value.username in CredHub server 1.2.0 and prior. This has been deprecated in favor of parameters.username.

HTTP Request

POST: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
mode converge no enum1 Overwrite interaction mode
parameters none no object Password generation parameters
parameters.username none no string User provided value for username
parameters.length 30 no integer Length of generated credential value
parameters.exclude_upper false no boolean Exclude upper alpha characters from generated credential value
parameters.exclude_lower false no boolean Exclude lower alpha characters from generated credential value
parameters.exclude_number false no boolean Exclude number characters from generated credential value
parameters.include_special false no boolean Include special characters from generated credential value

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.

Type: Certificate

CredHub CLI

user$ credhub generate --type certificate --name '/example-certificate' --common-name 'example.com' --ca '/example-ca'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-certificate
type: certificate
value:
  root: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X POST \
  -d '{
      "name": "/example-certificate",
      "type": "certificate"
      "parameters": {
        "common_name": "example.com",
        "ca": "/example-ca"
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "certificate",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "name": "/example-certificate",
  "value": {
    "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request generates a user credential based on the provided parameters.

HTTP Request

POST: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to generate
type none yes string Type of credential to generate
mode converge no enum1 Overwrite interaction mode
parameters none yes object Generation parameters
parameters.common_name none no2 string Common name of generated credential value
parameters.alternative_names none no array
parameters.alternative_names[] none no string Alternative names of generated credential value
parameters.organization none no2 string Organization of generated credential value
parameters.organization_unit none no2 string Organization Unit of generated credential value
parameters.locality none no2 string Locality/city of generated credential value
parameters.state none no2 string State/province of generated credential value
parameters.country none no2 string Country of generated credential value
parameters.key_usage none no array
parameters.key_usage[] none no enum3 Key usage extensions of generated credential value
parameters.extended_key_usage none no array
parameters.extended_key_usage[] none no enum4 Extended key usage extensions of generated credential value
parameters.key_length 2048 no enum5 Key length of generated credential value
parameters.duration 365 no integer Duration in days of generated credential value
parameters.ca none no6 credential7 Name of certificate authority to sign of generated credential value
parameters.is_ca false no6 boolean Whether to generate credential value as a certificate authority
parameters.self_sign false no6 boolean Whether to self-sign generated credential value

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 One subject field must be specified in the request
3 Acceptable key usages are digital_signature, non_repudiation, key_encipherment, data_encipherment, key_agreement, key_cert_sign, crl_sign, encipher_only and decipher_only.
4 Acceptable extended key usages are client_auth, server_auth, code_signing, email_protection and timestamping.
5 Acceptable key lengths are 2048, 3072, 4096
6 At least one signing parameter must be provided
7 Credential must contain appropriate certificate authority extensions

Type: RSA

CredHub CLI

user$ credhub generate --type rsa --name '/example-rsa'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-rsa
type: rsa
value:
  public_key: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X POST \
  -d '{
      "name": "/example-rsa",
      "type": "rsa"
      "parameters": {
        "key_length": 4096
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "rsa",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
  "name": "/example-rsa",
  "value": {
    "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request generates an RSA credential based on the provided parameters.

HTTP Request

POST: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
mode converge no enum1 Overwrite interaction mode
parameters none no object Generation parameters
parameters.key_length 2048 no enum2 Key length of generated credential value

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Acceptable key lengths are 2048, 3072, 4096

Type: SSH

CredHub CLI

user$ credhub generate --type ssh --name '/example-ssh'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-ssh
type: ssh
value:
  public_key: ssh-rsa AAAAB3NzaC1y...W9RWFM1
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/data" \
  -X POST \
  -d '{
      "name": "/example-ssh",
      "type": "ssh"
      "parameters": {
        "key_length": 4096
      }
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "ssh",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
  "name": "/example-ssh",
  "value": {
    "public_key": "ssh-rsa AAAAB3NzaC1y...W9RWFM1",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

This request generates an SSH credential based on the provided parameters.

HTTP Request

POST: https://example.com/api/v1/data

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to set
type none yes string Type of credential to set
mode converge no enum1 Overwrite interaction mode
parameters none no object Generation parameters
parameters.key_length 2048 no enum2 Key length of generated credential value
parameters.ssh_comment none no string SSH comment of generated credential value

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Acceptable key lengths are 2048, 3072, 4096

Regenerate Credentials

The regenerate endpoints generate new values for credentials using the same parameters as the stored value. All RSA and SSH credentials may be regenerated. Password and user credentials must have been generated to enable regeneration. Statically set certificates may be regenerated if they are self-signed or if the CA name has been set to a stored CA certificate.

Single Credential

CredHub CLI

user$ credhub regenerate --name '/example-password'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
name: /example-password
type: password
value: 3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R
version_created_at: 2017-01-01T04:07:18Z

cURL

curl "https://example.com/api/v1/regenerate" \
  -X POST \
  -d '{
      "name": "/example-password"
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "type": "password",
  "version_created_at": "2017-01-01T04:07:18Z",
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad674",
  "name": "/example-password",
  "value": "3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R"
}

This request regenerates a single credential by name.

NOTICE: Server version 1.4.0+ supports regenerate at path api/v1/regenerate, modified from api/v1/data in prior versions. Regenerate functionality on the data endpoint is still functional, but deprecated. You are advised to migrate to regenerate to avoid disruption when the deprecated functionality is removed.

HTTP Request

POST: https://example.com/api/v1/regenerate

Request Parameters

Parameter Default Required Type Description
name none yes string Name of credential to regenerate

Certificate Signed By a CA

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/bulk-regenerate" \
  -X POST \
  -d '{
      "signed_by": "/example-ca"
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
    "regenerated_credentials": [
        "/example-cert1",
        "/example-cert2",
        "/example-cert3"
    ]
}

This endpoint regenerates all certificate signed by the given CA.

NOTICE:
- This functionality was added in version 1.4.0. - As of version 1.7.0, bulk-regenerate will additionally traverse the pki chain to leaf certificates beyond one level down.

HTTP Request

POST: https://example.com/api/v1/bulk-regenerate

Request Parameters

Parameter Default Required Type Description
signed_by none yes string Name of CA whose signed certificates will be regenerated

Delete Credentials

CredHub CLI

user$ credhub delete --name '/example-password'
Credential successfully deleted

cURL

curl "https://example.com/api/v1/data?name=/example-password" \
  -X DELETE \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
[Status 204 Empty]

This request deletes a credential by name.

HTTP Request

DELETE: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to delete

Find Credentials

Find by Partial Name

CredHub CLI

user$ credhub find --name-like 'password'
credentials: 
- name: /password1
  version_created_at: 2017-05-09T21:09:26Z
- name: /test/example/password
  version_created_at: 2017-05-09T21:09:07Z

cURL

curl "https://example.com/api/v1/data?name-like=password" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "credentials": [
    {
      "version_created_at": "2017-05-09T21:09:26Z",
      "name": "/password1"
    },
    {
      "version_created_at": "2017-05-09T21:09:07Z",
      "name": "/test/example/password"
    }
  ]
}

This request retrieves a list of stored credential names which contain the search.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
name-like none true string Search term to match against stored credential names

Find by Path

CredHub CLI

user$ credhub find --path '/director-name/deployment-name'
credentials:
- name: /director-name/deployment-name/db-password
  version_created_at: 2017-05-09T21:09:26Z
- name: /director-name/deployment-name/user-password
  version_created_at: 2017-05-09T21:09:07Z
- name: /director-name/deployment-name/api-tls
  version_created_at: 2017-05-10T11:13:07Z

cURL

curl "https://example.com/api/v1/data?path=/director-name/deployment-name" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "credentials": [
    {
      "version_created_at": "2017-05-09T21:09:26Z",
      "name": "/director-name/deployment-name/db-password"
    },
    {
      "version_created_at": "2017-05-09T21:09:07Z",
      "name": "/director-name/deployment-name/user-password"
    },
    {
      "version_created_at": "2017-05-10T11:13:07Z",
      "name": "/director-name/deployment-name/api-tls"
    }
  ]
}

This request retrieves a list of stored credential names which are within the specified path.

HTTP Request

GET: https://example.com/api/v1/data

Query Parameters

Parameter Default Required Type Description
path none true string Path of credentials to return

Certificates

CA Rotation

CredHub offers support for zero-downtime rotation of certificate credentials by allowing certificates to have multiple “active” versions at the same time.

The workflow at a high-level for transitioning to a new certificate is:

  1. Regenerate your CA certificate with the transitional flag. This creates a new version that will not be used for signing yet, but can be added to your servers trusted certificate lists.
  2. Remove the transitional flag from the new certificate, and add it to the old certificate. This means that the new certificate will start to be used for signing, but the old one will remain as trusted.
  3. Remove the transitional flag from the old certificate. Now that all your clients should have certificates signed by the new CA’s certificate, the old one can be removed from your servers trusted lists.

Step 1: Regenerate

First we’ll need to get the ID of the certificate. Assuming you’re logged in with the CredHub CLI, this curl -k command will get you the ID:

curl "https://example.com/api/v1/certificates?name=[certificate-name]" -H "Content-Type: application/json" -H "Authorization: bearer [token]"

Next, we use that ID to generate the new, transitional version:

curl "https://example.com/api/v1/certificates/[certificate-id]/regenerate" -X POST -d '{"set_as_transitional": true}' -H "Content-Type: application/json" -H "Authorization: bearer [token]"

You should now see that when you request the “current” versions of that credential, that both certificates are returned:

curl "https://example.com/api/v1/data?name=[certificate-name]&current=true" -H "Content-Type: application/json" -H "Authorization: bearer [token]"

Step 2: Moving the transitional flag

To move the transitional flag off of the new certificate and onto the older version, we’ll need to grab the older versions ID:

curl "https://example.com/api/v1/data?name=[certificate-name]&current=true" -H "Content-Type: application/json" -H "Authorization: bearer [token]"

Find the ID of the certificate that currently has transitional: false, and then pass it to the next command:

curl "https://example.com/api/v1/certificates/[certificate-id]/update_transitional_version" -X PUT -d '{"version": "[Non-Transitional-ID]"}' -H "Content-Type: application/json" -H "Authorization: bearer [token]"

You can confirm that now the two certificates have swapped:

curl "https://example.com/api/v1/data?name=[certificate-name]&current=true" -H "Content-Type: application/json" -H "Authorization: bearer [token]"

Step 3: Removing the transitional flag

After you have regenerated all your client certificates to be signed by the new cert, you can safely remove the transitional flag from the old one:

curl "https://example.com/api/v1/certificates/[certificate-id]/update_transitional_version" -X PUT -d '{"version": null}' -H "Content-Type: application/json" -H "Authorization: bearer [token]"

You can now confirm that only one certificate is active:

curl "https://example.com/api/v1/data?name=[certificate-name]&current=true" -H "Content-Type: application/json" -H "Authorization: bearer [token]"

Get All Certificates

cURL

curl "https://example.com/api/v1/certificates" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "certificates": [
    {
      "name": "/example-certificate",
      "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d"
    }
  ]
}

This request retrieves all certificates.

HTTP Request

GET: https://example.com/api/v1/certificates

Query Parameters

Parameter Default Required Type Description
none

Get Certificate by Name

cURL

curl "https://example.com/api/v1/certificates?name=/example-certificate" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "certificates": [
    {
      "name": "/example-certificate",
      "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d"
    }
  ]
}

This request retrieves a certificate by name. Exactly one value will be returned. The id returned by the request represents the certificate version id. To get the id of the credential use api/v1/data

HTTP Request

GET: https://example.com/api/v1/certificates

Query Parameters

Parameter Default Required Type Description
name none yes string Name of credential to retrieve

Regenerate Certificate

cURL

curl "https://example.com/api/v1/certificates/[certificate-ID]/regenerate" \
  -X POST \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json' \
  -d '{"set_as_transitional": true/false}'
{
  "type": "certificate",
  "expiry_date": "2019-09-04T17:39:54Z",
  "transitional": true/false,
  "version_created_at": "2018-09-04T17:39:54Z",
  "id": "3e208a47-715d-4669-a3df-492b932a0c98",
  "name": "/example-certificate",
  "value": {
    "ca": "CA certificate",
    "certificate": "Certificate",
    "private_key": "Private-key"
  }
}

This regenerates a certificate. Only one version of a certificate may be transitional at a given time.

HTTP Request

POST: https://example.com/api/v1/certificates/[certificate-ID]/regenerate

Request Parameters

Parameter Default Required Type Description
set_as_transitional false no boolean Make version transitional or not

Update Transitional Version

cURL

curl "https://example.com/api/v1/certificates/[certificate-ID]/update_transitional_version" \
  -X PUT \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json' \
  -d '{"version": "[certificate-version]"}'
[
  {
    "type": "certificate",
    "expiry_date": "2019-09-04T17:51:45Z",
    "transitional": false,
    "version_created_at": "2018-09-04T17:51:45Z",
    "id": "3e208a47-715d-4669-a3df-492b932a0c98",
    "name": "/example-certificate",
    "value": {
      "ca": "CA certificate",
      "certificate": "Certificate",
      "private_key": "Private-key"
    }
  },
  {
    "type": "certificate",
    "expiry_date": "2019-09-04T17:52:40Z",
    "transitional": true,
    "version_created_at": "2018-09-04T17:52:40Z",
    "id": "be9ee5ca-69da-4e90-9d2d-b78a4a28625d",
    "name": "/example-certificate",
    "value": {
      "ca": "CA certificate",
      "certificate": "Certificate",
      "private_key": "Private-key"
    }
  }
]

This sets the given version of a certificate as transitional and marks the current transitional version, if one exists, as not transitional.

Setting "version": null will ensure no version is transitional.

Returns the latest certificate version in addition to the latest transitional version, if one exists.

HTTP Request

PUT: https://example.com/api/v1/certificates/[certificate-ID]/update_transitional_version

Request Parameters

Parameter Default Required Type Description
version none yes string The version to make transitional

Permissions

Permissions can be defined for namespaces as well as on explicit credential names. Permissions are additive – if any rule exists authorizing a user to take an action, then the action will be permitted.

Add Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v2/permissions" \
  -X POST \
  -d '
  {
    "path": "/example-directory/*",
    "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081"
    "operations": ["read", "write"]
  }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "uuid": "example-uuid",
  "path": "/example-directory/*",
  "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
  "operations": ["read","write"]
}
curl "https://example.com/api/v2/permissions" \
  -X POST \
  -d '
  {
    "path": "/example-directory/example-specific-credential",
    "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081"
    "operations": ["read", "write"]
  }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "uuid": "other-uuid",
  "path": "/example-directory/example-specific-credential",
  "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
  "operations": ["read","write"]
}

This request adds permissions for a path for an actor. You can add permission for a specific credential on a path, as well as all items under a path by using the * syntax.

HTTP Request

POST: https://example.com/api/v2/permissions

Request Parameters

Parameter Default Required Type Description
path none yes string A path where you would like to add a permission to for an actor
actor none yes string An actor that receives permission at the specified path
operations none yes array of strings List of operations given to actor for specified path

1 Authentication-specific identities explained here.
2 Supported operations: read, write, delete, read_acl, write_acl

Get Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v2/permissions/example-permission-uuid" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
   "path":"/example-credential-namespace",
   "operations":[
      "read",
      "write"
   ],
   "actor":"uaa-user:f6b2f8f6-1654-4a5d-aba4-c4d024a43560",
   "uuid":"example-permission-uuid"
} 

This request returns the permissions of a path given the permission UUID.

HTTP Request

GET: https://example.com/api/v2/permissions

Query Parameters

Parameter Default Required Type Description
uuid none yes string UUID of permission, that was returned when permission was created.

Update Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v2/permissions/example-permission-uuid" \
  -X PUT \
  -d '
  {
    "path": "/example-directory/example-credential",
    "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081"
    "operations": ["read", "write"]
  }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "uuid": "example-permission-uuid",
  "path": "/example-directory/example-credential",
  "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
  "operations": ["read","write"]
}
curl "https://example.com/api/v2/permissions/example-permission-uuid" \
  -X PATCH \
  -d '
  {
    "operations": ["read", "write"]
  }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "uuid": "example-permission-uuid",
  "path": "/example-directory/example-credential",
  "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
  "operations": ["read","write"]
}

This request updates the operations for a permission keeping the same path and actor. It replaces the operations that were set before with the new operations that are provided in the request.

HTTP Request

POST: https://example.com/api/v2/permissions

Request Parameters

Parameter Default Required Type Description
uuid none yes string The permission uuid that was returned when a permission was created
path none yes string The path of the permission you would like to update the operations for
actor none yes string The actor that you would like to update the operations for
operations none yes array of strings The new list of operations you would like to update this permission for

1 Authentication-specific identities explained here.
2 Supported operations: read, write, delete, read_acl, write_acl

Delete Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v2/permissions/example-permission-uuid" \
  -X DELETE \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "uuid": "example-permission-uuid",
  "path": "/example-specific-credential",
  "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
  "operations": ["read","write"]
}

This request deletes a permission.

HTTP Request

DELETE: https://example.com/api/v2/permissions/example-permission-uuid

Query Parameters

Parameter Default Required Type Description
uuid none yes string The UUID of the permission that was returned when permission was created.

1 Authentication-specific identities explained here.

Interpolate Endpoint

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/interpolate" \
  -X POST \
  -d '{ 
      "p-config-server": [
      {
       "credentials": {
         "credhub-ref": "/config-server/credentials"
       },
       "label": "p-config-server",
       "name": "config-server",
       "plan": "standard",
       "provider": null,
       "syslog_drain_url": null,
       "tags": [
        "configuration",
        "spring-cloud"
       ],
       "volume_mounts": []
      }]
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "p-config-server": [
  {
   "credentials": {
     "access_token_uri": "https://p-spring-cloud-services.uaa.example.com/oauth/token",
     "client_id": "p-config-server-d6ed7b18-5ae8-4642-af0c-11b1a47aad14",
     "client_secret": "example-secret",
     "uri": "https://config-2ad9cb93-d16d-4840-93ef-15b537c90847.apps.example.com"
   },
   "label": "p-config-server",
   "name": "config-server",
   "plan": "standard",
   "provider": null,
   "syslog_drain_url": null,
   "tags": [
    "configuration",
    "spring-cloud"
   ],
   "volume_mounts": []
   }]
}

This endpoint receives a VCAP_SERVICES object containing CredHub references and responds with the object containing the credential values interpolated.

NOTE: At this time, only credential references at credentials.credhub-ref will be interpolated. The key credhub-ref will be removed and the referenced credential object will be set as the value of credentials.

HTTP Request

POST: https://example.com/api/v1/interpolate

Query Parameters

Parameter Default Required Type Description
none

Encryption Key Usage

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/key-usage" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "active_key": 141240,
  "inactive_keys": 0,
  "unknown_keys": 0
}

This endpoint retrieves the number of credentials encrypted by the active key, provided inactive keys and unknown keys. After initiating an encryption key rotation, you may validate the status of the encryption key rotation, and whether it successfully rotated all of the stored data, using this endpoint.

HTTP Request

GET: https://example.com/api/v1/key-usage

Query Parameters

Parameter Default Required Type Description
none

Get Version

CredHub CLI

user$ credhub --version
CLI Version: 2.0.1
Server Version: 2.0.2

cURL

curl "https://example.com/version" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "version": "2.0.2"
}

This request displays the server version.

HTTP Request

GET: https://example.com/version

Request Parameters

Parameter Default Required Type Description
none

Health

CredHub CLI

[not supported]

cURL

curl "https://example.com/health" \
  -X GET
{
  "status": "UP"
}

This request verifies that communication with the server via the API is possible.

HTTP Request

GET: https://example.com/health

Request Parameters

Parameter Default Required Type Description
none

Errors

Error Code Meaning
400 The format of the request does not meet expectation
401 The request did not include a valid authentication method
403 The authenticated user is not authorized to perform the attempted operation
404 The resource does not exist or you are not authorized to access it
500 An internal server error occurred. Try again later or contact your administrator.

Integrations

BOSH Director

BOSH Manifest

variables:
- name: /example-user
  type: user
  options:
    username: admin
- name: /example-certificate
  type: certificate
  options:
    ca: /root-ca
    common_name: example.com
    alternative_names:
    - example.com
    - www.example.com
- name: example-password
  type: password
  options:
    length: 50

instance_groups:
- name: credhub-db
  instances: 1

  jobs:
  - name: example
    release: example
    properties:
      example:
        tls: ((/example-certificate))
        data_storage:
          type: postgres
          username: ((/example-user.username))
          password: ((/example-user.password))
        admin_password: ((example-password))

The integration with the BOSH Director allows you to reference existing or generate new credentials in CredHub. The generation functionality is driven by the variables section of the deployment manifest. Each variable in the list must contain a name, type and may contain generation parameters. All types and generation parameters offered by the API are supported using the BOSH manifest.

The object options passes through directly to the API request object parameters. Any parameter, e.g. common_name, alternative_names, duration, listed in the generation request parameters above can be provided in yaml format in the options configuration.

Concourse CI

Pipeline Configuration

resources:
- name: credhub-ci
  type: git
  source:
    uri: git@github.com:cloudfoundry-incubator/credhub
    branch: master
    private_key: ((ci-key.private_key))
- name: credhub-files
  type: s3
  source:
    bucket: credhub-example
    access_key_id: ((s3/write/access-key-id))
    secret_access_key: ((s3/write/secret-access-key))

jobs:
- name: credhub-example
  plan:
  - get: credhub-repo
  - task: deploy-something
    file: credhub-repo/tasks/task.yml
    params:
      BOSH_CLIENT: ((bosh-client.username))
      BOSH_CLIENT_SECRET: ((bosh-client.password))
  - put: credhub-files
    params:
      file: file.txt

The Concourse integration allows you to provide references to stored CredHub credentials in your pipeline configurations. The syntax for references is ((credential-name)). For multi-part credentials, like certificates, a single part of the credential can be provided using dot accessors, e.g. ((credential.certificate)) and ((credential.private_key)). More information can be found here.

Concourse does not currently support generation of credentials, so you must set or generate the credentials in CredHub prior to referencing them in your pipeline.