Authentication

Send a bearer credential in the Authorization header on every request:

Authorization: Bearer <credential>

Every credential belongs to exactly one workspace. Rills never picks a workspace from a request parameter, and changing your default workspace in the app doesn’t change what an existing key or connection can reach. To read two workspaces, use two credentials.

#Two kinds of credential

Both work with the REST API and the MCP server, and both are limited to the scopes they were granted.

#Create an API key

1. Open Settings → API & MCP access in the workspace the key should read.
2. Choose Create API key and give it a name that says where it will live, such as “Grafana – pipeline dashboard”.
3. Pick scopes. Start from a preset, then remove what the client doesn’t need:
   • Metadata only: every read scope except payloads:read. Enough for run, approval, and volume dashboards.
   • Full workspace read: every read scope plus payloads:read. Lets the key read row values, form submissions, workflow inputs and outputs, approval context, and agent conversations.
4. Copy the key. It’s shown once; Rills only stores a hash, so a lost key can’t be recovered. Create a new one and delete the old one.

You can edit a key’s scopes or delete it at any time. Deleting a key takes effect immediately.

See Scopes for what each scope grants.

#Connect with OAuth

MCP clients that support OAuth, such as Claude, can connect without a key:

1. Add the Rills MCP server URL to the client (see MCP).
2. The client opens Rills in your browser. Sign in.
3. Review the scopes the client is asking for and select the workspace it may use. If it asks for payloads:read, Rills calls that out separately.
4. Approve. The connection appears under Connected apps with its workspace, scopes, and last use.

An OAuth connection never exceeds your role. If you’re a viewer, a client can’t start workflows or decide approvals on your behalf even if it asked for those scopes. If you leave the workspace, the connection stops working at once. Adding scopes or switching workspaces requires approving the connection again.

#When authentication fails

A missing, invalid, expired, revoked, or unbound credential returns 401 UNAUTHORIZED with a WWW-Authenticate header. Its resource_metadata value is the absolute URL of the API’s OAuth protected-resource document, which OAuth-capable clients use to discover how to sign in:

WWW-Authenticate: Bearer resource_metadata="https://rills.ai/api/v1/.well-known/oauth-protected-resource"

A valid credential without the right scope returns 403 FORBIDDEN. See Pagination, errors & rate limits.

#Keep credentials secret

A Rills credential reads workspace data until you revoke it. Treat it like a password:

• Never in a browser. Don’t embed a key in frontend code, a browser extension, or a client-side dashboard query. The API doesn’t accept browser cross-origin calls for this reason.
• Never in a repository. Load keys from environment variables (for example $RILLS_API_KEY) or a secret manager, and keep .env files out of version control.
• Never in a panel or dashboard definition. In Grafana, store the key in the data source’s secure settings, not in a panel query or exported dashboard JSON. See Grafana.
• Never in a screenshot or ticket. Redact the key before sharing logs, screenshots, or support requests. Share the X-Request-Id instead.
• One key per destination. Separate keys for each tool make rotation and revocation painless.
• Narrowest scopes. Only grant payloads:read when the client must read the values themselves.

If a key may have leaked, delete it in Settings → API & MCP access right away and create a replacement.