Overview

Control access to your Flexprice resources with role-based permissions

Flexprice’s Role-Based Access Control (RBAC) system allows you to create service accounts with specific permissions for automated services and integrations. Instead of sharing your main account credentials, create dedicated service accounts with only the access they need.

What is RBAC?

RBAC lets you create service accounts for your automated systems - like event ingestion services, analytics dashboards, or CI/CD pipelines - and assign each one specific roles that control what it can access.

Key Benefits:

• Enhanced Security: Limit what each service can access
• Controlled Access: Assign specific permissions based on what each service needs to do
• Easy Management: Create and revoke service account access without affecting your main account
• Clear Separation: Different API keys for different purposes

How It Works

When you create a service account, you assign it one or more roles. Each role grants specific permissions to access certain resources.

Example Flow:

1. Create a service account and assign it the event_ingestor role
2. Generate an API key for that service account
3. The API key inherits the event_ingestor permissions
4. Your service can now ingest events but cannot access customer data or billing information

User Types

Regular Users (User Accounts)

Your standard user accounts for people. These accounts:

• Can log in to the dashboard
• Hold one of the organization-wide roles: super_admin, all_writer, or all_reader
• API keys from user accounts inherit the roles the user held when the key was created

A super_admin can change another user’s roles at any time. See Managing Roles.

Service Accounts

Automated accounts for your services and integrations. These accounts:

• Cannot log in to the dashboard
• Must have at least one role assigned
• Access Flexprice only through API keys
• API keys from service accounts have restricted access based on assigned roles
• Have fixed roles: a service account’s roles cannot be changed after creation

Run automation on service accounts

Give scripts, integrations, and scheduled jobs their own service account and use its API key. A workflow tied to user’s account stops working when their roles change or their account no longer exists.

Available Roles

Role	Account Type	Grants
super_admin	User and service account	Every action on every resource
all_writer	User account	Read and write on every resource
all_reader	User account	Read on every resource
event_ingestor	Service account	Send events
event_reader	Service account	Read events

super_admin

For services that need unrestricted access to every Flexprice resource.

Can do:

• Perform any action on any resource (read, write, delete)

Cannot do:

• Nothing. This role grants * permissions on * resources

Use for: Internal automation, migrations, or admin tooling that needs the same access as a user account. Treat the API key like a root credential.

Only assign super_admin when no narrower role works. Rotate keys frequently and store them in a secret manager.

all_writer

For teammates who manage billing configuration day to day.

Can do:

• Read every resource
• Write to every resource

Cannot do:

• Change any user’s roles, which requires super_admin

Use for: People who create plans, manage customers, and issue invoices.

all_reader

For teammates who review billing data without changing it.

Can do:

• Read every resource

Cannot do:

• Create, update, or delete anything

Use for: Finance reviewers, support staff checking a customer’s usage, read-only dashboards backed by a person’s account.

event_ingestor

For services that send events to Flexprice.

Can do:

• Send events

Cannot do:

• Read events
• Access any other resources

Use for: Event ingestion services, usage tracking tools

event_reader

For services that read event data.

Can do:

• Read events

Cannot do:

• Send events
• Modify any data

Use for: Analytics dashboards, reporting tools

Real-World Use Cases

Use Case 1: Event Ingestion Service

Scenario: You have a microservice that sends usage events to Flexprice.

Solution: Create a service account with the event_ingestor role and generate an API key.

What happens:

• ✅ Your service can send events successfully
• ❌ If it tries to read events, it gets 403 Forbidden
• ❌ It cannot access any other resources

Use Case 2: Analytics Dashboard

Scenario: Your analytics dashboard needs to read events for reporting.

Solution: Create a service account with the event_reader role and generate an API key.

What happens:

• ✅ Your dashboard can read event data
• ❌ If it tries to send events, it gets 403 Forbidden
• ❌ It cannot modify any data

Validation Rules

Service Accounts Require Roles

Every service account must have at least one role assigned. You cannot create a service account without specifying roles.

Common Validation Errors

Error: No Roles Assigned

{
  "error": "Service accounts must have at least one role assigned"
}

Error: Invalid Role

{
  "error": "Invalid role: custom_role"
}

Error Responses

403 Forbidden

When a service account tries to access a resource it doesn’t have permission for:

{
  "error": "Forbidden",
  "message": "Insufficient permissions to write event"
}

What this means: The API key doesn’t have the required permission. You need to:

1. Check which role the account behind the key has
2. Verify that role includes the permission you need
3. For a service account, create a replacement account with the role set you need, because service account roles are fixed at creation. For a user account, ask a super_admin to update the user’s roles
4. Generate a new API key (permissions are set when the key is created)

Getting Started

Step 1: Create a Service Account

Choose the appropriate role for your use case and create a service account:

curl --request POST \
  --url https://api.cloud.flexprice.io/v1/users \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "roles": [
    "<string>"
  ],
  "type": "user"
}'

Step 2: Generate an API Key

Create an API key for your service account:

curl --request POST \
  --url https://api.cloud.flexprice.io/v1/secrets/api/keys \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "expires_at": "<string>",
  "name": "<string>",
  "service_account_id": "<string>",
  "type": "private_key"
}'

The API key is only shown once. Copy and store it securely immediately.

Step 3: Use the API Key

Use the API key in your service:

curl --request POST \
  --url https://api.cloud.flexprice.io/v1/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "customer_id": "customer456",
  "event_id": "event123",
  "event_name": "api_request",
  "external_customer_id": "customer456",
  "properties": {
    "\"response_status\"": "200}",
    "{\"request_size\"": "100"
  },
  "source": "api",
  "timestamp": "2024-03-20T15:04:05Z"
}'

Best Practices

Use Specific Roles

Assign only the roles your service needs. Don’t use broader permissions than necessary.

Rotate API Keys Regularly

Generate new API keys periodically (recommended: every 90 days) and delete old ones.

Store Keys Securely

Use environment variables or secret management systems. Never commit API keys to your code repository.

Troubleshooting

Getting 403 Errors

Symptom: Your service is getting “Forbidden” errors when making API calls.

Possible Causes:

• The service account doesn’t have the role that grants the required permission
• The API key was created before you assigned roles to the service account
• You’re trying to access a resource that the assigned role doesn’t cover

Solution:

1. Check what roles the service account has
2. Verify those roles include the permission you need
3. If you recently added roles, create a new API key
4. Test with a simple request to verify permissions

Cannot Create Service Account

Symptom: Getting an error when trying to create a service account.

Possible Causes:

• Didn’t specify any roles
• Specified an invalid role name

Solution: Make sure you’re providing at least one valid role in the roles array.

Next Steps

Create Service Account

Learn how to create service accounts →

Managing Roles

Change the roles of a user in your organization →

Manage API Keys

Learn how to generate and manage API keys →