Instance Secret

The instance secret is a shared token that gates access to Opengram's write endpoints. When enabled, every mutating API request must present the secret or it will be rejected with a 401 Unauthorized response.

Enabling the Instance Secret

Set the following fields in opengram.config.json:

{
  "security": {
    "instanceSecretEnabled": true,
    "instanceSecret": "og_your-secret-here"
  }
}

When you run opengram init, the wizard generates a secret automatically using the og_ prefix followed by a random base64url string (e.g. og_a1B2c3D4e5F6...).

Authentication Methods

There are two ways to send the secret with a request.

Authorization Header

Include the token in the Authorization header using the Bearer scheme:

curl -X POST https://opengram.example.com/api/v1/chats \
  -H "Authorization: Bearer og_your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "default"}'

Query Parameter

For connections that do not support custom headers -- such as the SSE event stream -- pass the token as a token query parameter:

https://opengram.example.com/api/v1/events?token=og_your-secret-here

Read endpoint protection

By default, the following read-only GET endpoints do not require the instance secret:

• Chats (list, get, unread summary, pending summary)
• Messages (list)
• Requests (list)
• Media (list, get, download file, download thumbnail)
• Config (get)
• Search
• Tags (suggestions)
• Health

The SSE event stream (/api/v1/events/stream) is an exception — it always requires the instance secret when enabled, regardless of readEndpointsRequireInstanceSecret.

This allows lightweight integrations that only need to read data.

To require the secret on read endpoints as well, enable readEndpointsRequireInstanceSecret:

{
  "security": {
    "instanceSecretEnabled": true,
    "instanceSecret": "og_your-secret-here",
    "readEndpointsRequireInstanceSecret": true
  }
}

Environment variable override

You can set the instance secret via the OPENGRAM_INSTANCE_SECRET environment variable instead of (or in addition to) the config file. When this variable is set, it overrides security.instanceSecret and automatically enables security.instanceSecretEnabled.

This is especially useful for Docker deployments where you can pass it via -e or env_file without modifying opengram.config.json. See Environment Variables for the full list.

Best Practices

• Use a strong random token. The opengram init wizard generates one automatically. If you create one manually, use at least 32 characters of random base64url.
• Rotate periodically. Change the secret on a regular schedule. Update the config file and restart the server to apply a new secret.
• Never expose in client-side code. The instance secret should only be used in server-to-server communication or in trusted environments. Do not embed it in frontend JavaScript, mobile apps, or public repositories.