Service Tokens

Service tokens (also called service accounts) provide programmatic access to Rill Cloud for production systems, scheduled jobs, backend APIs, and other automated workflows. Unlike user tokens, service tokens persist even if the creating user is removed from the organization.

Overview

Service tokens are designed for:

• Production integrations - Backend services that need to access Rill APIs
• Scheduled jobs - Automated reports, data syncs, or ETL processes
• CI/CD pipelines - Automated testing and deployment workflows
• Custom applications - Applications that integrate with Rill APIs

Creating Service Tokens

Basic Creation

Create a service token with an organization-level role:

rill service create my-service --org-role admin

Or with a project-level role:

rill service create my-service --project my-project --project-role viewer

With Custom Attributes

Custom attributes allow you to pass metadata that can be used in security policies. This is particularly useful for multi-tenant applications or when you need fine-grained access control.

rill service create my-service \
  --org-role admin \
  --attributes '{"department":"engineering","region":"us-west","tier":"premium"}'

Example attributes:

• department - Organizational department (engineering, sales, finance)
• region - Geographic region (us-west, eu-central, ap-south)
• customer_id - Customer identifier for multi-tenant systems
• tier - Service tier (free, premium, enterprise)
• environment - Deployment environment (production, staging)

Complete Example

# Create a service for automated reporting
rill service create reporting-service \
  --org my-org \
  --project analytics-dashboard \
  --project-role viewer \
  --attributes '{"purpose":"reporting","schedule":"daily","region":"us-east"}'

The command will output:

Created service "reporting-service" in org "my-org".
Access token: rill_svc_[TOKEN_HERE]

Store tokens securely

Service tokens have powerful permissions. Store them securely in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) and never commit them to version control.

Roles and Permissions

Service tokens can be assigned roles at both the organization and project levels. For more details on using attributes with security policies, see the security policies documentation.

Managing Service Tokens

Listing Service Tokens

View all service tokens in your organization:

rill service list --org my-org

Output:

NAME                 ORG ROLE    PROJECT ROLES           ATTRIBUTES
reporting-service    -           analytics-dashboard     {"purpose":"reporting"}
global-admin         admin       -                       {}
dashboard-viewer     -           sales-analytics         {}

Editing Service Tokens

Update a service token's name or attributes:

# Change the name
rill service edit my-service --new-name renamed-service

# Update attributes
rill service edit my-service \
  --attributes '{"department":"finance","region":"eu-west"}'

# Clear attributes
rill service edit my-service --attributes '{}'

Managing Roles

Update organization role:

rill service set-role my-service --org-role editor

Add or update project role:

rill service set-role my-service \
  --project analytics-dashboard \
  --project-role admin

Remove project role:

rill service set-role my-service \
  --project analytics-dashboard \
  --remove

Viewing Service Details

Get detailed information about a service:

rill service show my-service --org my-org

Revoking Access

Delete a service token to immediately revoke its access:

rill service delete my-service --org my-org

Issuing Ephemeral Tokens

Service tokens can issue short-lived ephemeral tokens for end users. This is useful for:

• Embedded dashboards
• Temporary API access
• User-specific data access

With User Email

For simple cases, you can just provide the end user's email:

curl -X POST https://api.rilldata.com/v1/orgs/<org-name>/projects/<project-name>/credentials \
  -H "Authorization: Bearer <service-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "user@example.com",
    "ttl_seconds": 3600
  }'

The response contains a short-lived JWT token that can be used to access Rill APIs on behalf of the user.

With Custom User Attributes

For advanced cases, you can pass custom user attributes:

curl -X POST https://api.rilldata.com/v1/orgs/<org-name>/projects/<project-name>/credentials \
  -H "Authorization: Bearer <service-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "email": "user@example.com",
      "department": "sales",
      "region": "us-west",
      "customer_id": "acme-corp"
    },
    "ttl_seconds": 3600
  }'

The custom attributes can be referenced in the project's security policies. When using custom attributes, make sure that you pass a value for every attribute referenced in the project's security policies.

User identity

The user_email, attributes, and external_user_id parameters serve two purposes in ephemeral tokens:

• User attributes for security policies: user_email and attributes determine which attributes (such as email, domain, and admin) are available for use in security policies.
• Per-user state: external_user_id establishes a stable user identity that isolates per-user features such as AI chat history. Without a user identity, these features are not available.

Only one of user_email or attributes can be provided for a given token. The external_user_id parameter can optionally be combined with either of them. Here is how each parameter works:

• user_email: Looks up the user in Rill Cloud by email and populates their standard attributes. If no matching user is found, it generates limited attributes with only the fields email, domain and admin (set to false). Does not enable per-user state on its own; combine with external_user_id to enable per-user state.
• attributes: Passes the provided attributes through directly. Make sure to include all attributes referenced in your security policies (e.g. email, domain, admin, or custom attributes like tenant_id). Does not enable per-user state on its own; combine with external_user_id to enable per-user state.
• external_user_id: Any stable identifier for an external end user. This is usually the user's ID in your own database. Setting it enables per-user state such as AI chat history. Can be combined with user_email or attributes.