-
Notifications
You must be signed in to change notification settings - Fork 1
User Guide: Credentials and Secrets
Your app or service often needs a secret: a database password, an API key, an access token. The one rule: never type or paste a secret into the chat or an AI prompt. Chat is saved and may be sent to an AI provider, so a secret pasted into chat is no longer secret.
Instead, you store the secret once. OSC keeps it encrypted and hands the value to your app automatically when it runs. You will not see the value again in the dashboard or the AI. (OSC manages the encryption keys for you, so this is safe managed storage, not a "only you hold the key" vault. Store the kind of credentials you are comfortable trusting to a managed cloud service.)
| What you are doing | Use this |
|---|---|
| Deploying a ready-made service from the catalog (a database, a cache, etc.) | Service Secret |
| Deploying your own app (a My App) or a scheduled AI Agent Task | Parameter Store |
| Letting a script or agent act on your behalf in OSC | OSC Access Token |
Not sure? If you are deploying your own app or an agent task, you want the Parameter Store. Start with the Quickstart below.
Goal: give your app a database password without the password ever appearing in chat.
-
Create a parameter store (a private, encrypted place for your app's settings). In the console, go to My Apps and open Parameter Stores, then create one with an alphanumeric name such as
myappconfig(letters and numbers only, no spaces or hyphens). When it is ready you are shown an encryption key, once. Copy it now and keep it safe, it cannot be shown again. You need it later to link the store to your app. -
Add the secret in the store screen, not in chat. In your store, add an entry named
DATABASE_URL, mark it as a Secret, and paste the value (for examplepostgres://user:pass@host/db) into the form there. Entering it in the store form is what keeps it out of chat. Do not paste the value into the AI. -
Link the store to your app. When you create the app, select
myappconfigas its parameter store (and provide the key from step 1). The platform decrypts your secrets and gives them to the app as normal settings (environment variables) the moment it starts. -
Read it in your code like any normal setting, for example
process.env.DATABASE_URLin Node or$DATABASE_URLin a shell. The real value is there at runtime. You never handled the raw secret after step 2.
That is the whole happy path. Everything below is reference detail and less common cases.
A private, per-workspace store of settings for your My Apps and Agent Tasks. (A workspace is your OSC working area; a My App is your own app deployed on OSC; an Agent Task is a scheduled AI agent run.) It holds two kinds of entries:
- Plain settings for non-sensitive config (a base URL, a feature flag on or off).
- Secrets for anything sensitive (API keys, passwords, connection strings). Secrets are encrypted before they are stored. The decrypted value goes to your running app at startup; it is not shown back to you in the dashboard or the AI.
When you create a parameter store, OSC generates an encryption key for that store. This key is what unlocks the encrypted values so your app can read them at startup.
The key is shown once, right after the store is created. Copy it before closing that screen — it will not be shown again.
You do not type the key into your app's configuration yourself. When you link the parameter store to a My App or Agent Task, OSC automatically stores the key as a Service Secret and injects it at startup. The key never appears in any configuration field or chat message.
If you lose the key, you can regenerate it from the Stores screen — but every app and agent task linked to that store will need to be relinked with the new key.
The safe way to let AI handle the key: when an AI tool (such as Claude with MCP) sets up a My App or Agent Task for you, it receives a short-lived, protected download link for the key rather than the raw value. It uses that link to wire up the store automatically, without the key ever passing through the conversation. This is the right way to let AI handle parameter store setup.
One store can serve many apps and tasks in the same workspace. Full setup steps: see Parameter Store.
When you deploy a ready-made service from the catalog and it needs a credential, store it as a Service Secret attached to that service. You enter the value once, and after that it is never returned again through the API, the dashboard, or the AI. Use lowercase letters and numbers only, no spaces or hyphens (for example xwikipostgrespw).
To use it, reference it by name in the service's configuration:
{{secrets.mysecretname}}
Two things worth knowing:
-
A reference must be the entire value of a field. You cannot embed it inside a longer string. So instead of
redis://:{{secrets.password}}@host, store the whole line as one secret and reference that. (Plain English: put the full "address plus password" line in as a single secret, not just the password.) - Trade-off: because the whole line is one secret, when the password changes you update the entire entry, not just the password part.
Because the value is never returned, it is safe to inspect the service over the AI or the API: you see the reference name, never the real value.
An access token lets a script or an AI tool make OSC API calls as you. You create one in the console, choose how long it lasts (up to 90 days), and copy it once, right after creating it.
Treat it like a master key: it works across your whole account, so create one only when you need it, give it the shortest lifetime that works, and revoke it when you are done. If a token ever appears in chat, revoke it immediately (see "If you accidentally pasted a secret").
Tokens are listed and revoked from app.osaas.io/dashboard/profile/api.
When you deploy a catalog service that requires an OSC Access Token, there is a secure flow that keeps the value out of the conversation entirely:
- The AI tool mints a token by calling the OSC API.
- It receives a short-lived, protected download link — not the raw token value.
- It uses that link to store the token as a Service Secret, directly, without the value ever passing through the chat.
- The service configuration then uses
{{secrets.name}}to reference it, as with any other secret.
This is the right way to let an AI tool provision an OSC Access Token. What you should avoid is asking the AI to print the token value or paste it into a message — if the raw value appears in the conversation, it is no longer safe.
(Advanced: OSC can also issue narrower, shorter-lived tokens scoped to a single service, for tighter control. Most people do not need these.)
To deploy an app from a private GitHub, GitLab, or Gitea repo, register the repo's access token once as a git credential instead of pasting it anywhere:
- Ask to register a credential with a friendly name, for example
mygithubtoken. You get a one-time browser link, valid for 10 minutes. Open it and paste your token there. It goes straight from your browser and never passes through the chat.- Automating with no browser (a build server)? Ask for the setup instructions to get a ready-to-run command for your terminal. Put the token in your build server's own secret settings, not typed inline into the command.
- When you create or update the app, refer to the credential by its friendly name. The real token is never shown again.
- When the token expires, register a fresh one under the same name. The app restarts cleanly and keeps the same URL.
An Agent Task that calls an AI model needs a provider key. Store it as a Secret in the parameter store (entered in the store screen, never in the task prompt or the chat). Your options:
-
Anthropic API key (starts with
sk-ant-, from console.anthropic.com). Billed to your Anthropic account per token. -
OpenAI API key (starts with
sk-, from platform.openai.com). Needed if your Agent Task uses OpenAI's Codex model runner. Billed to your OpenAI account. - Claude OAuth token (signing in with your claude.ai account instead of using an API key). This is meant for your own personal use of Claude, tied to your account. If the task powers a service you offer to other people, do not use your personal sign-in, use an Anthropic API key.
Which to choose: for a task you run for yourself, any of these works. If it powers something you provide to others, use an API key (Anthropic or OpenAI), not a personal Claude sign-in.
When you list parameters without supplying the store's key, secret values show as ***. That is intentional masking. It means the value is stored and intact, encrypted, and will be delivered to your app correctly. It does not mean the value is missing.
One tip: do not try to read your own secret from inside a running task. The task already receives the real value as a normal setting at startup, so just read that. Reading the store from inside the task without the key returns ***, which is the correct, safe behavior.
Do this immediately, in order:
- Revoke or rotate the secret in the system that issued it (GitHub, your AI provider, your database console).
- Store the new value using one of the methods above.
- Assume the old one is compromised. A secret that appeared in chat is no longer secret.
A Personal Access Token can last up to 90 days. When it expires, calls made with that token stop working, so create a new one and update wherever you used it. Your already-running apps and agent tasks are not affected the same way: they keep running on a platform-managed credential and do not break the moment your PAT expires.
- Encryption key: protects the secrets stored in a Parameter Store. It is generated when the store is created and is used by OSC to decrypt secrets when an application starts.
- Workspace: your OSC working area, where your apps, stores, and services live.
- My App: your own application deployed on OSC from a git repository.
- Agent Task: a scheduled AI agent run on OSC.
- Service: a ready-made open-source product from the OSC catalog that you deploy (a database, a cache, and so on).
-
Environment variable: a named setting handed to your app when it starts, read in code as
process.env.NAMEor$NAME. This is how OSC delivers your secrets to your app. -
Connection string: a single line that tells an app how to reach a service, often containing a password, for example
postgres://user:pass@host/db. - AI coding tool (MCP client): an assistant such as Claude or Cursor that can connect to OSC and act for you.
- Encrypted (AES-256-GCM): scrambled with a strong, modern method so the stored data is unreadable without the key.