# Secrets

## Create Secret

`client.Secrets.New(ctx, body) (*CloudSecret, error)`

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

- `body SecretNewParams`

  - `Key param.Field[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 param.Field[string]`

    The secret value to store

  - `Description param.Field[string]`

    Optional human-readable description

### Returns

- `type CloudSecret struct{…}`

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

  - `ID string`

    The unique identifier of the entity.

  - `AccountID string`

    The ID of the account that owns the given entity.

  - `CloudSecretPath string`

    Full path in the cloud secret store.

  - `CreatedAt Time`

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

  - `CreatedBy Identity`

    The identity that created the entity.

    - `ID string`

    - `Type IdentityType`

      - `const IdentityTypeUser IdentityType = "user"`

      - `const IdentityTypeServiceAccount IdentityType = "service_account"`

    - `Object IdentityObject`

      - `const IdentityObjectIdentity IdentityObject = "identity"`

  - `Key string`

    Secret name, e.g. OPENAI_API_KEY.

  - `Description string`

    Optional human-readable description of the secret.

  - `Object CloudSecretObject`

    - `const CloudSecretObjectSGPCloudSecret CloudSecretObject = "sgp_cloud_secret"`

  - `UpdatedAt Time`

    Timestamp of last update.

  - `UpdatedBy string`

    User who last updated the secret.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  cloudSecret, err := client.Secrets.New(context.TODO(), sgpdev.SecretNewParams{
    Key: "key",
    Value: "x",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", cloudSecret.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

`client.Secrets.List(ctx, query) (*CursorPage[CloudSecret], error)`

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

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

### Parameters

- `query SecretListParams`

  - `EndingBefore param.Field[string]`

  - `Limit param.Field[int64]`

  - `SortBy param.Field[string]`

  - `SortOrder param.Field[SortOrder]`

  - `StartingAfter param.Field[string]`

### Returns

- `type CloudSecret struct{…}`

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

  - `ID string`

    The unique identifier of the entity.

  - `AccountID string`

    The ID of the account that owns the given entity.

  - `CloudSecretPath string`

    Full path in the cloud secret store.

  - `CreatedAt Time`

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

  - `CreatedBy Identity`

    The identity that created the entity.

    - `ID string`

    - `Type IdentityType`

      - `const IdentityTypeUser IdentityType = "user"`

      - `const IdentityTypeServiceAccount IdentityType = "service_account"`

    - `Object IdentityObject`

      - `const IdentityObjectIdentity IdentityObject = "identity"`

  - `Key string`

    Secret name, e.g. OPENAI_API_KEY.

  - `Description string`

    Optional human-readable description of the secret.

  - `Object CloudSecretObject`

    - `const CloudSecretObjectSGPCloudSecret CloudSecretObject = "sgp_cloud_secret"`

  - `UpdatedAt Time`

    Timestamp of last update.

  - `UpdatedBy string`

    User who last updated the secret.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  page, err := client.Secrets.List(context.TODO(), sgpdev.SecretListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

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

`client.Secrets.Get(ctx, secretID) (*CloudSecret, error)`

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

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

### Parameters

- `secretID string`

### Returns

- `type CloudSecret struct{…}`

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

  - `ID string`

    The unique identifier of the entity.

  - `AccountID string`

    The ID of the account that owns the given entity.

  - `CloudSecretPath string`

    Full path in the cloud secret store.

  - `CreatedAt Time`

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

  - `CreatedBy Identity`

    The identity that created the entity.

    - `ID string`

    - `Type IdentityType`

      - `const IdentityTypeUser IdentityType = "user"`

      - `const IdentityTypeServiceAccount IdentityType = "service_account"`

    - `Object IdentityObject`

      - `const IdentityObjectIdentity IdentityObject = "identity"`

  - `Key string`

    Secret name, e.g. OPENAI_API_KEY.

  - `Description string`

    Optional human-readable description of the secret.

  - `Object CloudSecretObject`

    - `const CloudSecretObjectSGPCloudSecret CloudSecretObject = "sgp_cloud_secret"`

  - `UpdatedAt Time`

    Timestamp of last update.

  - `UpdatedBy string`

    User who last updated the secret.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  cloudSecret, err := client.Secrets.Get(context.TODO(), "secret_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", cloudSecret.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

`client.Secrets.Update(ctx, secretID, body) (*CloudSecret, error)`

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

- `secretID string`

- `body SecretUpdateParams`

  - `Description param.Field[string]`

    Updated human-readable description

  - `Value param.Field[string]`

    Updated secret value to store in cloud provider

### Returns

- `type CloudSecret struct{…}`

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

  - `ID string`

    The unique identifier of the entity.

  - `AccountID string`

    The ID of the account that owns the given entity.

  - `CloudSecretPath string`

    Full path in the cloud secret store.

  - `CreatedAt Time`

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

  - `CreatedBy Identity`

    The identity that created the entity.

    - `ID string`

    - `Type IdentityType`

      - `const IdentityTypeUser IdentityType = "user"`

      - `const IdentityTypeServiceAccount IdentityType = "service_account"`

    - `Object IdentityObject`

      - `const IdentityObjectIdentity IdentityObject = "identity"`

  - `Key string`

    Secret name, e.g. OPENAI_API_KEY.

  - `Description string`

    Optional human-readable description of the secret.

  - `Object CloudSecretObject`

    - `const CloudSecretObjectSGPCloudSecret CloudSecretObject = "sgp_cloud_secret"`

  - `UpdatedAt Time`

    Timestamp of last update.

  - `UpdatedBy string`

    User who last updated the secret.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  cloudSecret, err := client.Secrets.Update(
    context.TODO(),
    "secret_id",
    sgpdev.SecretUpdateParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", cloudSecret.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

`client.Secrets.Delete(ctx, secretID) error`

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

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

### Parameters

- `secretID string`

### Example

```go
package main

import (
  "context"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  err := client.Secrets.Delete(context.TODO(), "secret_id")
  if err != nil {
    panic(err.Error())
  }
}
```

## Domain Types

### Cloud Secret

- `type CloudSecret struct{…}`

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

  - `ID string`

    The unique identifier of the entity.

  - `AccountID string`

    The ID of the account that owns the given entity.

  - `CloudSecretPath string`

    Full path in the cloud secret store.

  - `CreatedAt Time`

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

  - `CreatedBy Identity`

    The identity that created the entity.

    - `ID string`

    - `Type IdentityType`

      - `const IdentityTypeUser IdentityType = "user"`

      - `const IdentityTypeServiceAccount IdentityType = "service_account"`

    - `Object IdentityObject`

      - `const IdentityObjectIdentity IdentityObject = "identity"`

  - `Key string`

    Secret name, e.g. OPENAI_API_KEY.

  - `Description string`

    Optional human-readable description of the secret.

  - `Object CloudSecretObject`

    - `const CloudSecretObjectSGPCloudSecret CloudSecretObject = "sgp_cloud_secret"`

  - `UpdatedAt Time`

    Timestamp of last update.

  - `UpdatedBy string`

    User who last updated the secret.