Skip to content

Authentication

Rig accepts four kinds of credential. Which one applies depends on the interface.

Credential Used for Sent as
API token Workflow triggers, the MCP server, SCIM Authorization: Bearer rig_mcp_...
OAuth 2.1 The MCP server, for interactive clients Handled by the MCP client
HMAC signature Inbound webhook triggers X-Rig-Signature header
User session Preview operations in the API reference Authorization: Bearer <session token>

API tokens

An API token is a long-lived secret that belongs to the user who created it and to one workspace.

rig_mcp_<client_id>_<64 hexadecimal characters>

Send it in the Authorization header:

curl https://app.rig.so/jaffleshop/workflows/WORKFLOW_ID/runs/RUN_ID \
  -H "Authorization: Bearer rig_mcp_jaffleshop_EXAMPLE"

Properties:

  • Shown once. The token value is returned when it is created and cannot be retrieved later. Rig stores a SHA-256 hash of the token, not the token.
  • Bound to one workspace. A token is rejected on any other workspace's paths.
  • Acts as its principal. A token created by a user runs with that user's role and data permissions, and stops working if the user no longer has a role in the workspace. A token created for an agent runs as the agent, with the agent's own role, not as the owner who created it; it stops working when the agent is deleted or loses its role.
  • No expiry. A token is valid until it is revoked. Rotate a token by creating a new one and revoking the old one.
  • Revocable. Revoke a token in the application or with DELETE /{client_id}/api-tokens/{token_id}. Revocation takes effect within about a minute.

Scopes

A token's scopes object limits what it can do.

Scope Grants
{"mcp": true} Access to the MCP server. This is the default when no scopes are given.
{"workflows": {"trigger": ["<workflow_id>"]}} Start and poll runs of the listed workflows. Use "*" in place of the list for any workflow the token's owner can run.
{"tools": ["<tool_name>"]} Restricts an MCP token to the listed tools. Without this key the token can call every tool its owner's role permits.
{"people": {"source": "<name>"}} Write access to the people directory as one named source. The SCIM endpoint requires the source scim.

Scopes can be combined in one token.

Creating a token

  • Workflow trigger tokens are created from a workflow's API access panel in the application. Creating one requires the editor role or above.
  • Tokens for automated agents are created by a workspace owner under Access, Agents. An agent is a non-human identity with its own role, a tool profile (read-only by default) and an optional daily call limit. Agents authenticate with a token only.
  • People-directory tokens can be created only by a workspace owner.

A signed-in user can also create a token with POST /{client_id}/api-tokens (Preview), sending a JSON body with name and scopes.

A request with a missing, unknown or revoked token receives 401. A token used outside its scope receives 403 with the code token_scope_mismatch.

OAuth for MCP

Interactive MCP clients sign in with OAuth 2.1. The client does this for you: it discovers the authorisation server, registers itself, and opens a browser window where you sign in to Rig.

Item Value
Flow Authorisation code with PKCE (S256)
Client registration Dynamic client registration
Authorisation server metadata GET /.well-known/oauth-authorization-server
Protected resource metadata GET /.well-known/oauth-protected-resource
Scopes profile, email

An OAuth session acts as the signed-in user, with that user's role and data permissions in each workspace they belong to.

User sessions

Operations marked Preview in the API reference authenticate with the session token issued when a user signs in to the application. They are intended for the application itself and for exploration. There is no client-credentials grant for these operations today. For unattended integration, use an API token with the interfaces that accept one.

Roles

Every credential resolves to a user and that user's role in the workspace. The built-in roles, in ascending order, are viewer, analyst, editor and owner. Schema, table, column and row permissions for that role are applied to SQL run through the API and through the MCP server.

Rate limits

Interface Default limit Over the limit
HTTP API 120 requests per minute per client IP address 429
MCP server 60 requests per minute per credential 429 with a Retry-After header
Token creation 10 requests per minute 429

Limits are applied per server process and can be configured per deployment. Treat these figures as defaults, not as a guaranteed allowance, and retry 429 responses with backoff.