Retrieve a secret

Fetches the value of a secret from the specified variable. The latest version will be retrieved unless the version parameter is specified. The twenty most recent secret versions are retained.

The secret data is returned in the response body.

Conjur Cloud allows you to add a secret to any resource, but best practice is to store and retrieve secret data only using variable resources.

URI

GET /api/secrets/conjur/{kind}/{identifier}{?version}

Example URI

GET /api/secrets/conjur/variable/data/db/password?version=1

URI Parameters

Parameter	Type	Mandatory	Description
kind	String	Yes	should be “variable” Example: `variable`
identifier	String	Yes	The ID of the variable. Example: `data/db/password` Note: For ephemeral secrets, the identifier always starts with `data/ephemerals/`
version	integer	No	The version you want to retrieve (Conjur Cloud keeps the last 20 versions of a secret) Example: `1`

Parameter

Type

Mandatory

Description

kind

String

Yes

should be “variable”

Example: variable

identifier

String

Yes

The ID of the variable.

Example: data/db/password

Note: For ephemeral secrets, the identifier always starts with data/ephemerals/

version

integer

The version you want to retrieve (Conjur Cloud keeps the last 20 versions of a secret)

Example: 1

Any identifier included in the URL must be URL-encoded to be recognized by the Conjur Cloud API. For example:

Identifier	URL-Encoded
`data/myapp-01`	`data%2Fmyapp-01`
`alice@example.com`	`alice%40example.com`
`data/prod/aws/db-password`	`data%2Fprod%2Faws%2Fdb-password`
`data/research+development`	`data%2Fresearch%2Bdevelopment`
`data/sales&marketing`	`data%2Fsales%26marketing`

Example with curl

curl -H 'Authorization: Token token="<the token>"' \
    https://<subdomain>.secretsmgr.cyberark.cloud/api/secrets/conjur/variable/data/prod/db/password

If you are working with an Edge, replace <subdomain>.secretsmgr.cyberark.cloud with the Edge server's domain name, for example, example.com.

curl -H 'Authorization: Token token="<the token>"' \
    https://example.com/api/secrets/conjur/variable/data/prod/db/password

Response

Code	Description
200	The secret values was retrieved successfully. A response for an ephemeral secret includes the ID of the secret, the TTL value, details about the secrets, based on the type of issuer and the method used to create the secret. For AWS: Federation token method returns `federated_user_arn` and `federated_user_id` Assumed role method returns `assumed_role_user_id` and `assumed_role_user_arn`
401	The request lacks valid authentication credentials.
403	The authenticated user lacks the necessary privilege.
404	The variable does not exist, or it does not have any secret values.
422	A request parameter was missing or invalid.

Example responses

Response 200

Headers

Content-Type: application/octet-stream

The default setting for Content-type is application/octet-stream. If needed, you can overwrite the Content-type setting. For more information, see mime_type.

Body

c3c60d3f266074

Response 200 - ephemeral secret

The ephemeral secret retrieval returns all the information about the secret, as declared in the secret's variable definition. For details, see Declare a variable for an ephemeral secret.

Headers

Content-Type: application/json

Body

{
  "id": "b549465d-140b-475e-ada3-bc50e07d09da",
  "ttl": 1000,
  "data": {
    "access_key_id": "ASIATPD7AGKZWELYL6ET",
    "secret_access_key": "PleTNFflGV1Vz18gFW/jsOzyyq/U3PNGpeIfxwCR",
    "session_token": "IQoJb3J...3QcGAPoPc0BOtQn+5gfFpq8eHYr0zyBdifGERWtV0CZbqdzFzR",
    "federated_user_id": "238637036211:conjur,host,data.my-app",
    "federated_user_arn": "arn:aws:sts::238637036211:federated-user/conjur,host,data.my-app"
  }
}