Secrets

Secrets store sensitive data like API keys, passwords, and tokens. All secret values are encrypted at rest and access is logged for security auditing.

Secret Endpoints

Method	Endpoint	Description
`GET`	`/api/secrets/`	List all your secrets
`POST`	`/api/secrets/`	Create a new secret
`GET`	`/api/secrets/{id}/`	Get secret details
`PATCH`	`/api/secrets/{id}/`	Update a secret
`DELETE`	`/api/secrets/{id}/`	Delete a secret

Secret Item Endpoints

Method	Endpoint	Description
`GET`	`/api/secrets/{secret_id}/items/`	List secret items
`POST`	`/api/secrets/{secret_id}/items/`	Add a secret item
`GET`	`/api/secrets/{secret_id}/items/{id}/`	Get a secret item
`PATCH`	`/api/secrets/{secret_id}/items/{id}/`	Update a secret item
`DELETE`	`/api/secrets/{secret_id}/items/{id}/`	Delete a secret item

Secret Object

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "production-secrets",
  "is_default": false,
  "status": "ready",
  "deploy_successful": true,
  "created_at": "2024-10-15T10:00:00Z"
}

Fields

Field	Type	Description
`id`	UUID	Unique identifier (read-only)
`name`	string	Secret name
`is_default`	boolean	Whether this is the default secret (read-only)
`status`	string	Current status (read-only)
`deploy_successful`	boolean	Whether synced successfully (read-only)

Secret Item Object

json

{
  "id": "abc123...",
  "secret": "secret-uuid",
  "key": "API_KEY",
  "value": "sk_live_abc123...",
  "last_accessed_at": "2024-10-15T14:30:00Z",
  "last_accessed_by": "user-uuid",
  "created_at": "2024-10-15T10:00:00Z",
  "updated_at": "2024-10-15T12:00:00Z"
}

Fields

Field	Type	Description
`id`	UUID	Unique identifier (read-only)
`secret`	UUID	Parent secret ID (read-only)
`key`	string	Secret key name
`value`	string	Secret value (encrypted at rest)
`last_accessed_at`	datetime	When the value was last read (read-only)
`last_accessed_by`	UUID	Who last accessed the value (read-only)

List Secrets

http

GET /api/secrets/

Example:

bash

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/secrets/

Response:

json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "abc123...",
      "name": "Default",
      "is_default": true,
      "status": "ready"
    },
    {
      "id": "def456...",
      "name": "production-secrets",
      "is_default": false,
      "status": "ready"
    }
  ]
}

Create Secret

http

POST /api/secrets/

Request Body:

json

{
  "name": "production-secrets"
}

Example:

bash

curl -X POST https://api.example.com/api/secrets/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-secrets"}'

Delete Secret

http

DELETE /api/secrets/{id}/

Restrictions

Default secrets cannot be deleted - Every account has a default secret that cannot be removed
Secrets in use cannot be deleted - Remove the secret from all services first

List Secret Items

http

GET /api/secrets/{secret_id}/items/

Example:

bash

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/secrets/abc123.../items/

Response:

json

{
  "count": 2,
  "results": [
    {
      "id": "item1...",
      "key": "DATABASE_PASSWORD",
      "value": "********",
      "last_accessed_at": "2024-10-15T14:30:00Z"
    },
    {
      "id": "item2...",
      "key": "API_KEY",
      "value": "********",
      "last_accessed_at": null
    }
  ]
}

Value Visibility

In the web interface, secret values are hidden by default. Use the "show" button to reveal them. Each time you view a value, it's logged for auditing.

Add Secret Item

http

POST /api/secrets/{secret_id}/items/

Request Body:

json

{
  "key": "DATABASE_PASSWORD",
  "value": "super-secret-password"
}

Example:

bash

curl -X POST https://api.example.com/api/secrets/abc123.../items/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "API_KEY",
    "value": "sk_live_abc123xyz789"
  }'

Automatic Encryption

Values are automatically encrypted before storage. You don't need to encrypt them yourself.

Update Secret Item

http

PATCH /api/secrets/{secret_id}/items/{id}/

Example:

bash

curl -X PATCH https://api.example.com/api/secrets/abc123.../items/item1.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"value": "new-secret-password"}'

Delete Secret Item

http

DELETE /api/secrets/{secret_id}/items/{id}/

Example:

bash

curl -X DELETE https://api.example.com/api/secrets/abc123.../items/item1.../ \
  -H "Authorization: Bearer gob_your_key"

Rate Limiting

Secret access is rate limited to prevent abuse:

100 requests per hour for reading secret values

When rate limited:

json

{
  "detail": "Request was throttled. Expected available in 3600 seconds."
}

Access Auditing

Every time a secret value is accessed, Goblins logs:

When: Timestamp of access
Who: User who accessed the value

This information is visible on each secret item:

last_accessed_at: When the value was last read
last_accessed_by: Who read it

Security Best Practices

1. Use Secrets for Sensitive Data

Store these in secrets (not configs):

API keys and tokens
Database passwords
Private keys
OAuth client secrets
Encryption keys

2. Rotate Secrets Regularly

Update secrets periodically:

bash

curl -X PATCH https://api.example.com/api/secrets/abc123.../items/item1.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"value": "new-rotated-password"}'

3. Use Separate Secrets per Environment

Create different secrets for development, staging, and production:

bash

# Production secrets
curl -X POST https://api.example.com/api/secrets/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-secrets"}'

# Staging secrets
curl -X POST https://api.example.com/api/secrets/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging-secrets"}'

4. Monitor Access Logs

Regularly review last_accessed_at and last_accessed_by to detect unauthorized access.

Example Workflow

1. Create a Secret

bash

SECRET=$(curl -s -X POST https://api.example.com/api/secrets/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-secrets"}')

SECRET_ID=$(echo $SECRET | jq -r '.id')

2. Add Secret Items

bash

# Add database password
curl -X POST https://api.example.com/api/secrets/$SECRET_ID/items/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_PASSWORD", "value": "super-secret-db-password"}'

# Add API key
curl -X POST https://api.example.com/api/secrets/$SECRET_ID/items/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "STRIPE_SECRET_KEY", "value": "sk_live_..."}'

3. Use in Service

bash

curl -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "image": "myapp:v1.0.0",
    "port": 8080,
    "config": "your-config-id",
    "secret": "'$SECRET_ID'"
  }'

Next Steps

Configs - Non-sensitive configuration
Services - Attach secrets to services

Secrets ​

Secret Endpoints ​

Secret Item Endpoints ​

Secret Object ​

Fields ​

Secret Item Object ​

Fields ​

List Secrets ​

Create Secret ​

Delete Secret ​

List Secret Items ​

Add Secret Item ​

Update Secret Item ​

Delete Secret Item ​

Rate Limiting ​

Access Auditing ​

Security Best Practices ​

1. Use Secrets for Sensitive Data ​

2. Rotate Secrets Regularly ​

3. Use Separate Secrets per Environment ​

4. Monitor Access Logs ​

Example Workflow ​

1. Create a Secret ​

2. Add Secret Items ​

3. Use in Service ​

Next Steps ​

Secrets

Secret Endpoints

Secret Item Endpoints

Secret Object

Fields

Secret Item Object

Fields

List Secrets

Create Secret

Delete Secret

List Secret Items

Add Secret Item

Update Secret Item

Delete Secret Item

Rate Limiting

Access Auditing

Security Best Practices

1. Use Secrets for Sensitive Data

2. Rotate Secrets Regularly

3. Use Separate Secrets per Environment

4. Monitor Access Logs

Example Workflow

1. Create a Secret

2. Add Secret Items

3. Use in Service

Next Steps