Skill Secrets

Some skills need access to external services — a weather API, a CRM, a database, or a third-party platform. Secrets let you store API keys, tokens, and other credentials securely so your skills can authenticate without exposing sensitive values.

Secrets are encrypted at rest and never included in plain text in prompts, logs, or API responses.

When you need secrets

You need a secret any time a skill interacts with an external service that requires authentication. Common examples:

• API keys for third-party services (weather, maps, data providers)
• OAuth tokens for platform integrations (CRM, project management tools)
• Database connection strings
• Webhook signing keys

If your skill only processes text and does not call external services, you do not need secrets.

Step 1: Create a secret

1. Log in to your systemprompt.io dashboard
2. Navigate to Secrets in the sidebar
3. Click Create Secret
4. Fill in the fields:

Field	Description
Name	A unique identifier for the secret (e.g., weather_api_key)
Value	The actual credential (e.g., your API key)
Description	A note about what this secret is for (e.g., "OpenWeather API key for the weather skill")

5. Click Save

The secret is encrypted and stored. The value is write-only — once saved, it cannot be viewed again in the dashboard. You can only replace it with a new value.

Step 2: Reference a secret in your skill

Once a secret exists, you reference it in your skill configuration by name.

1. Open the skill in the dashboard
2. Go to the Secrets tab in the skill editor
3. Click Add Secret Reference
4. Select the secret by name (e.g., weather_api_key)
5. Save the skill

The skill now has access to that secret at runtime. When the skill executes, the platform securely injects the secret value where needed.

You do not put the secret value in your instructions. The platform handles injection automatically based on the secret references you configure.

Step 3: Use secrets in skill instructions

In your skill instructions, reference secrets by their configured name. The platform resolves the reference at runtime:

Use the weather API to fetch the current forecast.
API endpoint: https://api.openweather.org/data/3.0/onecall
Authentication: Use the weather_api_key secret for the API key parameter.

The skill knows which secret to use because you linked it in Step 2. The actual API key value is injected securely at execution time.

Secret scoping

Secrets are scoped to your account by default. This means:

• Your secrets are available only to your skills
• Team secrets can be created by organization administrators and are available to all skills within the organization
• Published skills that require secrets will prompt users to provide their own credentials when they install the skill

When you publish a skill that uses secrets, the secret values are never shared. Instead, users who install the skill are asked to supply their own API keys and credentials. The skill references remain the same — only the underlying values differ per user.

Rotating secrets

Credentials expire or get compromised. To rotate a secret:

1. Go to Secrets in the dashboard
2. Find the secret you need to update
3. Click Edit
4. Enter the new value
5. Click Save

The new value takes effect immediately for all skills that reference that secret. You do not need to update or republish any skills.

Deleting secrets

To remove a secret you no longer need:

1. Go to Secrets in the dashboard
2. Find the secret
3. Click Delete
4. Confirm the action

Before deleting, check which skills reference the secret. Any skill that references a deleted secret will fail when it tries to use that credential. Update or remove the secret reference from affected skills first.

Security best practices

• Use descriptive names — github_deploy_token is better than token1. Clear names prevent mistakes when managing multiple secrets.
• One secret per credential — Do not combine multiple keys into a single secret. Store each credential separately so you can rotate them independently.
• Rotate regularly — Update API keys on a schedule, especially for production services. The rotation process takes seconds and has zero downtime.
• Audit your secrets — Periodically review your secrets list and delete any that are no longer in use. Stale credentials are a security risk.
• Do not put secrets in instructions — Never paste an API key directly into a skill's instruction text. Always use the secret reference mechanism. Hardcoded credentials can leak through logs and version history.
• Use team secrets for shared credentials — If multiple team members need the same API key, have an administrator create a team secret rather than duplicating the credential across accounts.

How secrets are secured

systemprompt.io uses the following measures to protect your secrets:

• Encryption at rest — All secret values are encrypted before storage
• Write-only access — Secret values cannot be read back through the dashboard or API after creation
• Scoped access — Skills can only access secrets that are explicitly linked to them
• No logging — Secret values are never written to application logs or audit trails
• Isolated execution — Secrets are injected at runtime in an isolated context and are not included in prompt history

Troubleshooting

• Skill fails with "missing secret" — Open the skill editor, go to the Secrets tab, and verify the secret reference is configured. Check that the secret exists in your Secrets list.
• API returns 401 after rotation — Confirm you saved the new value. Open the secret, enter the new credential again, and save. The old value may not have been replaced if the save was interrupted.
• Team members cannot use a secret — Personal secrets are not shared. Ask an organization administrator to create a team secret instead.
• Cannot view a secret value — This is by design. Secret values are write-only for security. If you need to verify a credential, replace it with a known-good value.