# Secrets

## Create Secret

**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.

### Body Parameters

- `key: string`

  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: string`

  The secret value to store

- `description: optional string`

  Optional human-readable description

### Returns

- `CloudSecret object { id, account_id, cloud_secret_path, 7 more }`

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

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: string`

    Full path in the cloud secret store.

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `key: string`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: optional string`

    Optional human-readable description of the secret.

  - `object: optional "sgp_cloud_secret"`

    - `"sgp_cloud_secret"`

  - `updated_at: optional string`

    Timestamp of last update.

  - `updated_by: optional string`

    User who last updated the secret.

### Example

```http
curl https://api.egp.scale.com/v5/sgp/secrets \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "key": "key",
          "value": "x"
        }'
```

#### 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

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

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

### Query Parameters

- `ending_before: optional string`

- `limit: optional number`

- `sort_by: optional string`

- `sort_order: optional SortOrder`

  - `"asc"`

  - `"desc"`

- `starting_after: optional string`

### Returns

- `has_more: boolean`

  Whether there are more items left to be fetched.

- `items: array of CloudSecret`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: string`

    Full path in the cloud secret store.

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `key: string`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: optional string`

    Optional human-readable description of the secret.

  - `object: optional "sgp_cloud_secret"`

    - `"sgp_cloud_secret"`

  - `updated_at: optional string`

    Timestamp of last update.

  - `updated_by: optional string`

    User who last updated the secret.

- `total: number`

  The total of items that match the query. This is greater than or equal to the number of items returned.

- `limit: optional number`

  The maximum number of items to return.

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/sgp/secrets \
    -H "x-api-key: $SGP_API_KEY"
```

#### 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

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

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

### Path Parameters

- `secret_id: string`

### Returns

- `CloudSecret object { id, account_id, cloud_secret_path, 7 more }`

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

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: string`

    Full path in the cloud secret store.

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `key: string`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: optional string`

    Optional human-readable description of the secret.

  - `object: optional "sgp_cloud_secret"`

    - `"sgp_cloud_secret"`

  - `updated_at: optional string`

    Timestamp of last update.

  - `updated_by: optional string`

    User who last updated the secret.

### Example

```http
curl https://api.egp.scale.com/v5/sgp/secrets/$SECRET_ID \
    -H "x-api-key: $SGP_API_KEY"
```

#### 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

**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.

### Path Parameters

- `secret_id: string`

### Body Parameters

- `description: optional string`

  Updated human-readable description

- `value: optional string`

  Updated secret value to store in cloud provider

### Returns

- `CloudSecret object { id, account_id, cloud_secret_path, 7 more }`

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

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: string`

    Full path in the cloud secret store.

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `key: string`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: optional string`

    Optional human-readable description of the secret.

  - `object: optional "sgp_cloud_secret"`

    - `"sgp_cloud_secret"`

  - `updated_at: optional string`

    Timestamp of last update.

  - `updated_by: optional string`

    User who last updated the secret.

### Example

```http
curl https://api.egp.scale.com/v5/sgp/secrets/$SECRET_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{}'
```

#### 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

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

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

### Path Parameters

- `secret_id: string`

### Example

```http
curl https://api.egp.scale.com/v5/sgp/secrets/$SECRET_ID \
    -X DELETE \
    -H "x-api-key: $SGP_API_KEY"
```

## Domain Types

### Cloud Secret

- `CloudSecret object { id, account_id, cloud_secret_path, 7 more }`

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

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `cloud_secret_path: string`

    Full path in the cloud secret store.

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `key: string`

    Secret name, e.g. OPENAI_API_KEY.

  - `description: optional string`

    Optional human-readable description of the secret.

  - `object: optional "sgp_cloud_secret"`

    - `"sgp_cloud_secret"`

  - `updated_at: optional string`

    Timestamp of last update.

  - `updated_by: optional string`

    User who last updated the secret.