# Create and read a secret

Keep an API key or a password as a secret, add a new version to rotate it, and read its value from the console or the API.

Keep a value your software needs, such as an API key, as a secret of a project or an organization. To create a secret and add versions, you need Owner, Editor or Secret Manager Admin. To read its value, you need Owner, Secret Manager Admin or Secret Accessor.

Create a secret in the organization when several projects need it, and [share it](/guides/secrets/share-a-secret) with them. Otherwise, create it in the project.

## Create a secret [#create-a-secret]

1. In your project or organization, click **Access**, then **Secrets**.
2. Click **New secret**.
3. Enter a **Name**, such as `stripe/secret_key`: lowercase letters, digits, `_` and `/`.
4. Optionally, enter a **Description (optional)** that says what it's for.
5. Enter the **Value**, up to 64 KiB.
6. Click **Create secret**.

The secret's page opens, with the value as version 1.

## Rotate a value [#rotate-a-value]

Add the new value as a version, move your software to it, and then disable the old one. Software that reads `latest` gets the new value at once.

1. On the secret's page, click **New version**.
2. Enter the new **Value**.
3. To stop the old values working at once, select **Disable earlier versions**.
4. Click **Add version**.

## Read a value [#read-a-value]

1. On the secret's **Versions** tab, open the version's menu and click **Show value**.
2. Click **Show value** in the dialog, which says that the audit log records it.

## Disable or destroy a version [#disable-or-destroy-a-version]

- **Disable** a version to stop software reading it, as when you think it leaked. **Enable** brings it back.
- **Destroy** a version to delete its value for good. Software that reads it fails.

On the secret's **Versions** tab, open the version's menu and click **Disable**, **Enable** or **Destroy**.

## Use the API [#use-the-api]

Set your API key ([Call the API](/get-started/call-the-api)), your project's ID and the secret value to store. Then create the secret:

```sh
export KOSEM_API_KEY='kosem_sk_…'
export KOSEM_PROJECT='prj_01m5r9dh9mf0ps98ktkap3562c'
export STRIPE_SECRET_KEY='sk_test_…'

curl -s -X POST "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/secrets" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias": "stripe/secret_key", "description": "Stripe key for the checkout service"}'
```

kosem answers with the secret, which has no version yet:

```json
{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c/secrets/sec_01m5rd7wq3e9vbt6g0d4x7qz1p",
  "alias": "stripe/secret_key",
  "description": "Stripe key for the checkout service",
  "latestVersion": 0
}
```

Keep its ID, and add the value as a version. Values are base64, so that they can hold any bytes:

```sh
export KOSEM_SECRET='sec_01m5rd7wq3e9vbt6g0d4x7qz1p'

curl -s -X POST "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/secrets/$KOSEM_SECRET/versions" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"payload\": {\"data\": \"$(printf %s "$STRIPE_SECRET_KEY" | base64 | tr -d '\n')\"}}"
```

```json
{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c/secrets/sec_01m5rd7wq3e9vbt6g0d4x7qz1p/versions/1",
  "state": "ENABLED"
}
```

Read the latest enabled version's value, and decode it:

```sh
curl -s "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/secrets/$KOSEM_SECRET/versions/latest/access" \
  -H "Authorization: Bearer $KOSEM_API_KEY" | jq -r .payload.data | base64 --decode
```

To find a secret's ID by its name, look it up: `GET /v1/projects/$KOSEM_PROJECT/secrets/lookup?alias=stripe/secret_key`.

## Related [#related]

- [Secrets](/concepts/secrets)
- [Give an agent a secret](/guides/secrets/give-an-agent-a-secret)
- [Limits and quotas](/reference/limits#secrets)
