# Secrets

## Create Secret

`secrets.create(SecretCreateParams**kwargs)  -> CloudSecret`

**post** `/v5/sgp/secrets`

Create an account-level secret.

The secret value is stored in the cloud provider's secret store.
SGP only stores metadata (key name, description, audit info).
The value is never returned by any API.
Returns 409 if a secret with the same key already exists.

### Parameters

- `key: str`

  Secret name (e.g. openai-api-key). Must be lowercase alphanumeric with hyphens (no dots or underscores), so it maps 1:1 to a valid secret name on every cloud backend (AWS / Azure Key Vault / GCP Secret Manager).

- `value: str`

  The secret value to store

- `description: Optional[str]`

  Optional human-readable description

### Returns

- `class CloudSecret: …`

  API response model for a secret. Never includes the secret value.

  - `id: str`

    The unique identifier of the entity.

  - `account_id: str`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: str`

    Full path in the cloud secret store.

  - `created_at: datetime`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `key: str`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: Optional[str]`

    Optional human-readable description of the secret.

  - `object: Optional[Literal["sgp_cloud_secret"]]`

    - `"sgp_cloud_secret"`

  - `updated_at: Optional[datetime]`

    Timestamp of last update.

  - `updated_by: Optional[str]`

    User who last updated the secret.

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
cloud_secret = client.secrets.create(
    key="key",
    value="x",
)
print(cloud_secret.id)
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "cloud_secret_path": "cloud_secret_path",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "key": "key",
  "description": "description",
  "object": "sgp_cloud_secret",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "updated_by": "updated_by"
}
```

## List Secrets

`secrets.list(SecretListParams**kwargs)  -> SyncCursorPage[CloudSecret]`

**get** `/v5/sgp/secrets`

List secret metadata for the account. Values are never returned.

### Parameters

- `ending_before: Optional[str]`

- `limit: Optional[int]`

- `sort_by: Optional[str]`

- `sort_order: Optional[SortOrder]`

  - `"asc"`

  - `"desc"`

- `starting_after: Optional[str]`

### Returns

- `class CloudSecret: …`

  API response model for a secret. Never includes the secret value.

  - `id: str`

    The unique identifier of the entity.

  - `account_id: str`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: str`

    Full path in the cloud secret store.

  - `created_at: datetime`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `key: str`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: Optional[str]`

    Optional human-readable description of the secret.

  - `object: Optional[Literal["sgp_cloud_secret"]]`

    - `"sgp_cloud_secret"`

  - `updated_at: Optional[datetime]`

    Timestamp of last update.

  - `updated_by: Optional[str]`

    User who last updated the secret.

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
page = client.secrets.list()
page = page.items[0]
print(page.id)
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "account_id": "account_id",
      "cloud_secret_path": "cloud_secret_path",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "key": "key",
      "description": "description",
      "object": "sgp_cloud_secret",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "updated_by": "updated_by"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}
```

## Get Secret

`secrets.retrieve(strsecret_id)  -> CloudSecret`

**get** `/v5/sgp/secrets/{secret_id}`

Get a single secret's metadata by ID. The value is never returned.

### Parameters

- `secret_id: str`

### Returns

- `class CloudSecret: …`

  API response model for a secret. Never includes the secret value.

  - `id: str`

    The unique identifier of the entity.

  - `account_id: str`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: str`

    Full path in the cloud secret store.

  - `created_at: datetime`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `key: str`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: Optional[str]`

    Optional human-readable description of the secret.

  - `object: Optional[Literal["sgp_cloud_secret"]]`

    - `"sgp_cloud_secret"`

  - `updated_at: Optional[datetime]`

    Timestamp of last update.

  - `updated_by: Optional[str]`

    User who last updated the secret.

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
cloud_secret = client.secrets.retrieve(
    "secret_id",
)
print(cloud_secret.id)
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "cloud_secret_path": "cloud_secret_path",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "key": "key",
  "description": "description",
  "object": "sgp_cloud_secret",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "updated_by": "updated_by"
}
```

## Update Secret

`secrets.update(strsecret_id, SecretUpdateParams**kwargs)  -> CloudSecret`

**patch** `/v5/sgp/secrets/{secret_id}`

Update an existing secret's description and/or value.

If value is provided, the cloud provider secret is updated.
The secret value is never returned by any API.

### Parameters

- `secret_id: str`

- `description: Optional[str]`

  Updated human-readable description

- `value: Optional[str]`

  Updated secret value to store in cloud provider

### Returns

- `class CloudSecret: …`

  API response model for a secret. Never includes the secret value.

  - `id: str`

    The unique identifier of the entity.

  - `account_id: str`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: str`

    Full path in the cloud secret store.

  - `created_at: datetime`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `key: str`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: Optional[str]`

    Optional human-readable description of the secret.

  - `object: Optional[Literal["sgp_cloud_secret"]]`

    - `"sgp_cloud_secret"`

  - `updated_at: Optional[datetime]`

    Timestamp of last update.

  - `updated_by: Optional[str]`

    User who last updated the secret.

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
cloud_secret = client.secrets.update(
    secret_id="secret_id",
)
print(cloud_secret.id)
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "cloud_secret_path": "cloud_secret_path",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "key": "key",
  "description": "description",
  "object": "sgp_cloud_secret",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "updated_by": "updated_by"
}
```

## Delete Secret

`secrets.delete(strsecret_id)`

**delete** `/v5/sgp/secrets/{secret_id}`

Delete a secret from both the cloud provider and SGP metadata.

### Parameters

- `secret_id: str`

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
client.secrets.delete(
    "secret_id",
)
```

## Domain Types

### Cloud Secret

- `class CloudSecret: …`

  API response model for a secret. Never includes the secret value.

  - `id: str`

    The unique identifier of the entity.

  - `account_id: str`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: str`

    Full path in the cloud secret store.

  - `created_at: datetime`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `key: str`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: Optional[str]`

    Optional human-readable description of the secret.

  - `object: Optional[Literal["sgp_cloud_secret"]]`

    - `"sgp_cloud_secret"`

  - `updated_at: Optional[datetime]`

    Timestamp of last update.

  - `updated_by: Optional[str]`

    User who last updated the secret.