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 -, and forward slash / 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 is 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

By default, credential set and generate actions with the API will not overwrite an existing value. If you wish to only create values that do not exist, you can perform generate requests on all of the credentials and it leave existing values in place. This mode is the default, but can be specified as "mode" : "no-overwrite".

If you wish to overwrite existing values, you can set ‘mode’ as ‘overwrite’ or ‘converge’. When "mode" : "converge" is set, a new value will be generated only if the generation parameters have changed. When "mode" : "overwrite" is set, a new credential is generated in every case.

In versions prior to 1.6, mode is not available. Instead overwrite is indicated as a boolean value. If you wish to overwrite existing values, you should then include the "overwrite": true parameter in your request.

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",
    "version": "1.2.0"
  }
}

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 can not 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
type: password
name: /example-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'
{
  "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d",
  "name": "/example-password",
  "type": "password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
  "version_created_at": "2017-01-05T01:01:01Z"
}

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
type: password
name: /example-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": [
    {
      "id": "2993f622-cb1e-4e00-a267-4b23c273bf3d",
      "name": "/example-password",
      "type": "password",
      "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
      "version_created_at": "2017-01-05T01:01:01Z"
    },
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad674",
      "name": "/example-password",
      "type": "password",
      "value": "3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R",
      "version_created_at": "2017-01-01T04:07:18Z"
    }
  ]
}

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
type: value
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-value",
      "type": "value",
      "value": "sample",
      "version_created_at": "2017-01-01T04:07:18Z"
    }
  ]
}

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
type: json
name: /example-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": [
    {
      "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"
    }
  ]
}

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
type: password
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-password",
      "type": "password",
      "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
      "version_created_at": "2017-01-05T01:01:01Z"
    }
  ]
}

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
type: user
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
      "name": "/example-user",
      "type": "user",
      "value": {
        "username": "FQnwWoxgSrDuqDLmeLpU",
        "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
        "password_hash": "$6$uu8ybZiNiPRu$6AYClxVqMXA3LAIdDAnEuWLUlWGlm0RRJI2wdHd8R9hKkKtiYupyKBjdRBI1ZhsyHwYetCpySew9ZXXLf.Mih0"
      },
      "version_created_at": "2017-01-05T01:01:01Z"
    }
  ]
}

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
type: certificate
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
      "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-----"
      },
      "version_created_at": "2017-01-01T04:07:18Z"
    }
  ]
}

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 Return only latest credential version
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
type: rsa
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
      "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-----"
      },
      "version_created_at": "2017-01-01T04:07:18Z"
    }
  ]
}

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
type: ssh
name: /example-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": [
    {
      "id": "67fc3def-bbfb-4953-83f8-4ab0682ad678",
      "name": "/example-ssh",
      "type": "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"
      },
      "version_created_at": "2017-01-01T04:07:18Z"
    }
  ]
}

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, that 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
type: value
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-value",
  "type": "value",
  "value": "sample",
  "version_created_at": "2017-01-01T04:07:18Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes string Value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

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
type: json
name: /example-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'
{
  "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"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes object Value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: Password

CredHub CLI

user$ credhub set --type password --name '/example-password' --password '3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: password
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-password",
  "type": "password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
  "version_created_at": "2017-01-05T01:01:01Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes string Value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: User

CredHub CLI

user$ credhub set --type user --name '/example-user' --username 'FQnwWoxgSrDuqDLmeLpU' --password '6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: user
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-user",
  "type": "user",
  "value": {
    "username": "FQnwWoxgSrDuqDLmeLpU",
    "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
    "password_hash": "$6$uu8ybZiNiPRu$6AYClxVqMXA3LAIdDAnEuWLUlWGlm0RRJI2wdHd8R9hKkKtiYupyKBjdRBI1ZhsyHwYetCpySew9ZXXLf.Mih0"
  },
  "version_created_at": "2017-01-05T01:01:01Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
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
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

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
type: certificate
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "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-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes object
value.ca null no2,3 string Certificate authority value of credential to set
value.ca_name null no3 string Name of CA credential in credhub that has signed this certificate
value.certificate null no2 string Certificate value of credential to set
value.private_key null no2 string Private key value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity4 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum5 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 At least one value must be set
3 ‘ca_name’ and ‘ca’ are mutually exclusive values
4 Authentication-specific identities explained here.
5 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: RSA

CredHub CLI

user$ credhub set --type rsa --name '/example-rsa' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: rsa
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "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-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes object
value.public_key null no2 string Public key value of credential to set
value.private_key null no2 string Private key value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity3 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum4 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 At least one value must be set
3 Authentication-specific identities explained here.
4 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: SSH

CredHub CLI

user$ credhub set --type ssh --name '/example-ssh' --public ./public.pem --private ./private.pem
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: ssh
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "name": "/example-ssh",
  "type": "ssh",
  "value": {
    "public_key": "ssh-rsa AAAAB3NzaC1y...W9RWFM1",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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
mode no-overwrite no enum1 Overwrite interaction mode
value none yes object
value.public_key null no2 string Public key value of credential to set
value.private_key null no2 string Private key value of credential to set
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity3 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum4 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’ and ‘overwrite’ explained here.
2 At least one value must be set
3 Authentication-specific identities explained here.
4 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Bulk Import

CredHub CLI

user$ credhub import --file import.yml
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: ssh
name: /example-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
type: password
name: /example-password
value: SqFcE2c0AuRvet2YhrxdFbPtkBmjiq
version_created_at: 2017-01-01T04:07:28Z

id: 22a1e87b-ba0b-4bc9-bb26-4e5fc5fb1b2f
type: value
name: /example-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
type: password
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-password",
  "type": "password",
  "value": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL",
  "version_created_at": "2017-01-05T01:01:01Z"
}

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 no-overwrite 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
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’, and ‘write_acl’

Type: User

CredHub CLI

user$ credhub generate --type user --name '/example-user'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: user
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad675",
  "name": "/example-user",
  "type": "user",
  "value": {
    "username": "FQnwWoxgSrDuqDLmeLpU",
    "password": "6mRPZB3bAfb8lRpacnXsHfDhlPqFcjH2h9YDvLpL"
  },
  "version_created_at": "2017-01-05T01:01:01Z"
}

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 no-overwrite 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
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity2 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum3 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Authentication-specific identities explained here.
3 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

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
type: certificate
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad676",
  "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-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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 no-overwrite 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
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity8 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum9 Operation provided on credential to specified actor

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
8 Authentication-specific identities explained here.
9 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: RSA

CredHub CLI

user$ credhub generate --type rsa --name '/example-rsa'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: rsa
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
  "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-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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 no-overwrite no enum1 Overwrite interaction mode
parameters none no object Generation parameters
parameters.key_length 2048 no enum2 Key length of generated credential value
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity3 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum4 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Acceptable key lengths are 2048, 3072, 4096
3 Authentication-specific identities explained here.
4 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

Type: SSH

CredHub CLI

user$ credhub generate --type ssh --name '/example-ssh'
id: 67fc3def-bbfb-4953-83f8-4ab0682ad675
type: ssh
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad677",
  "name": "/example-ssh",
  "type": "ssh",
  "value": {
    "public_key": "ssh-rsa AAAAB3NzaC1y...W9RWFM1",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  },
  "version_created_at": "2017-01-01T04:07:18Z"
}

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 no-overwrite 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
additional_permissions none no array List of additional permissions to set on credential
additional_permissions[].actor none no identity3 Actor to provided specified operations on credential
additional_permissions[].operations none no array List of operations provided on credential to specified actor
additional_permissions[].operations[] none no enum4 Operation provided on credential to specified actor

1 Acceptable modes are ‘no-overwrite’, ‘overwrite’, and ‘converge’ explained here.
2 Acceptable key lengths are 2048, 3072, 4096
3 Authentication-specific identities explained here.
4 Acceptable operations are ‘read’, ‘write’, ‘delete’, ‘read_acl’ and ‘write_acl’

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
type: password
name: /example-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'
{
  "id": "67fc3def-bbfb-4953-83f8-4ab0682ad674",
  "name": "/example-password",
  "type": "password",
  "value": "3t6Y2OFP0jQIcLnki1h7p3NtSfDx4l9bamr1ja6R",
  "version_created_at": "2017-01-01T04:07:18Z"
}

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

Show All Paths

CredHub CLI

user$ credhub find --all-paths
paths: 
- path: /
- path: /director-name/
- path: /director-name/deploy1/
- path: /director-name/deploy2/
- path: /director2/

cURL

curl "https://example.com/api/v1/data?paths=true" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "paths": [
    {
      "path": "/"
    },
    {
      "path": "/director-name/"
    },
    {
      "path": "/director-name/deploy1/"
    },
    {
      "path": "/director-name/deploy2/"
    },
    {
      "path": "/director2/"
    }
  ]
}

This request retrieves a list of all paths which contain credentials.

HTTP Request

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

Query Parameters

Parameter Default Required Type Description
paths none true boolean Will return list of all paths if true

Permissions

Get Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/permissions?credential_name=/example-password" \
  -X GET \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "credential_name": "/example-password",
  "permissions": [
    {
      "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
      "operations": [
        "read",
        "write",
        "delete",
        "read_acl",
        "write_acl"
      ]
    }
  ]
}

This request returns the permissions of a credential.

HTTP Request

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

Query Parameters

Parameter Default Required Type Description
credential_name none yes string Name of credential whose permissions will be returned

Add Permissions

CredHub CLI

[not supported]

cURL

curl "https://example.com/api/v1/permissions" \
  -X POST \
  -d '{
      "credential_name": "/example-password",
      "permissions": [
      {
        "actor": "uaa-user:f6b2f8f6-1654-4a5d-aba4-c4d024a43560",
        "operations": ["read"]
      }]
     }' \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
{
  "credential_name": "/example-password",
  "permissions": [
    {
      "actor": "uaa-user:106f52e2-5d01-4675-8d7a-c05ff9a2c081",
      "operations": [
        "read",
        "write",
        "delete",
        "read_acl",
        "write_acl"
      ]
    },{
      "actor": "uaa-user:f6b2f8f6-1654-4a5d-aba4-c4d024a43560",
      "operations": ["read"]
    }
  ]
}

This request adds permissions to a credential.

HTTP Request

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

Request Parameters

Parameter Default Required Type Description
credential_name none yes string Name of credential whose permissions will be returned
permissions[] none yes array Permissions to add
permissions[n].actor none yes identity1 Actor provided permission
permissions[n].operations[] none yes array Operations to add
permissions[n].operations[n] none yes operation2 Operation provided to Actor

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/v1/permissions?credential_name=/example-password&actor=uaa-user:f6b2f8f6-1654-4a5d-aba4-c4d024a43560" \
  -X DELETE \
  -H "authorization: bearer [token]" \
  -H 'content-type: application/json'
[Status 204 Empty]

This request deletes a permission for an actor on a credential.

HTTP Request

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

Query Parameters

Parameter Default Required Type Description
credential_name none yes string Name of credential whose permissions will be deleted
actor none yes identity1 Name of actor whose permissions will be deleted

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

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.