Creating a Service Account

A service account is a special type of account for automated services, integrations, and scripts. Unlike your regular user account, service accounts are assigned specific roles that control what resources they can access in Flexprice.

Why Use Service Accounts?

Service accounts let you:

Isolate access: Each service gets its own account with only the permissions it needs
Improve security: If an API key is compromised, the damage is limited to that service’s permissions
Track usage: See which service is making which API calls
Manage easily: Revoke access for one service without affecting others

Creating a Service Account

Choose the Right Role

Before creating a service account, decide which role fits your use case: Flexprice currently supports following custom roles:

Role	Use When
`super_admin`	Your service needs full, unrestricted access (treat the key as a root credential)
`all_reader`	Your service needs to read every resource but never write anywhere (read-only API keys)
`event_ingestor`	Your service needs to send events to Flexprice
`event_reader`	Your service needs to read event data

Via Dashboard

Navigate to Developers > Service Accounts and click Create to open the service account creation dialog.

In the dialog:

Enter a name for the service account
Select the roles you want to assign, for example all_reader for a read-only integration or event_ingestor for an event pipeline
Click Create Service Account

The service account is created with the selected roles and you can now generate API keys for it.

Via API

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

const response = await fetch('https://api.cloud.flexprice.io/v1/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<api-key>'
  },
  body: JSON.stringify({
    type: 'service_account',
    name: 'Event Ingestion Worker',
    roles: ['event_ingestor']
  })
});

import requests

response = requests.post(
    'https://api.cloud.flexprice.io/v1/users',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': '<api-key>'
    },
    json={
        'type': 'service_account',
        'name': 'Event Ingestion Worker',
        'roles': ['event_ingestor']
    }
)

Response

{
  "id": "user_0123ABCD",
  "name": "Event Ingestion Worker",
  "type": "service_account",
  "roles": ["event_ingestor"],
  "tenant": {
    "id": "tenant_xyz789",
    "name": "Acme Inc",
    "status": "published",
    "created_at": "2025-01-20T14:13:31Z",
    "updated_at": "2026-09-08T08:37:06Z"
  }
}

Save the id from the response. You’ll need it when creating API keys.

Read-Only Service Account

To issue read-only API keys, create a service account with the all_reader role. Keys created for this account can read every resource in the environment and get 403 Forbidden on any write.

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

{
  "id": "user_0123ABCD",
  "name": "Reporting Sync",
  "type": "service_account",
  "roles": ["all_reader"],
  "tenant": {
    "id": "tenant_xyz789",
    "name": "Acme Inc",
    "status": "published",
    "created_at": "2025-01-20T14:13:31Z",
    "updated_at": "2026-09-08T08:37:06Z"
  }
}

Then create an API key with service_account_id set to the returned id. The key inherits all_reader.

Request Fields

string

required

Must be set to "service_account".

array

required

List of roles to assign. Must include at least one role.Available roles:

super_admin - Full access to every resource
all_reader - Can read every resource, cannot write
event_ingestor - Can send events
event_reader - Can read events

string

Display name shown in the dashboard and audit logs. Helps you identify the service account later when listing or updating it.

Validation Rules

At Least One Role RequiredYou must assign at least one role when creating a service account. Empty roles will return an error.

Common Errors

No Roles Provided

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

Invalid Role Name

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

Role Not Allowed for Service Accounts

{
  "code": "validation_error",
  "message": "Role 'all_writer' cannot be assigned to a 'service_account' account",
  "http_status_code": 400
}

Real-World Examples

Example 1: Event Ingestion Service

Scenario: You have a service that sends user events to Flexprice. Create service account with:

Role: event_ingestor

What happens:

✅ Service can send events
❌ Service cannot read events (403 Forbidden)
❌ Service cannot access other resources (403 Forbidden)

Example 2: Analytics Dashboard

Scenario: You have a dashboard that displays event data. Create service account with:

Role: event_reader

What happens:

✅ Dashboard can read events
❌ Dashboard cannot send events (403 Forbidden)
❌ Dashboard cannot modify anything (403 Forbidden)

Example 3: Reporting or Data Warehouse Sync

Scenario: A nightly job pulls customers, subscriptions, invoices, and usage into your data warehouse. It never writes to Flexprice. Create service account with:

Role: all_reader

What happens:

✅ Job can read every resource (customers, plans, subscriptions, invoices, wallets, events)
❌ Job cannot create, update, or delete anything (403 Forbidden)

This is the role to use whenever you need a read-only API key.

Assigning Multiple Roles

You can assign more than one role to give combined permissions: Service account with both roles:

Roles: event_ingestor and event_reader

What happens:

✅ Can send events (from event_ingestor)
✅ Can read events (from event_reader)

Updating a Service Account

Rename a service account at any time. Only the display name can be changed; roles and type are immutable.

curl --request PUT \
  --url https://api.cloud.flexprice.io/v1/users/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "Event Ingestion Worker (prod)"
}'

Deleting a Service Account

Archive a service account when it is no longer in use. Existing API keys for that account stop working immediately.

curl --request DELETE \
  --url https://api.cloud.flexprice.io/v1/users/{id} \
  --header 'x-api-key: <api-key>'

The endpoint returns 204 No Content on success. The account is soft-deleted, so its history remains in audit logs.

Best Practices

One Service Account Per ServiceCreate separate service accounts for each automated service or integration.

Assign Minimal PermissionsOnly assign the roles your service actually needs.

Troubleshooting

Service Getting 403 Errors

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

The service account doesn’t have the required role
The API key was created before you assigned roles
The role doesn’t include permission for that endpoint

Solution:

Check what roles the service account has: GET /v1/users/usr_abc123
Verify those roles include the permission you need
If you recently added roles, create a new API key

Cannot Create Service Account

Symptom: Getting an error when creating the service account. Possible Causes:

Forgot to include roles in the request
Used an invalid role name
Specified roles as an empty array

Solution: Make sure your request includes at least one valid role:

{
  "type": "service_account",
  "roles": ["event_ingestor"]
}

Next Steps

Generate API Keys

Create API keys for your service account →

Introduction

Getting Started

Event Ingestion

Product Catalogue

Customers

Checkout

Subscriptions

Wallet

Invoices

Settings

Collectors

Data Exports

RBAC

Cookbooks

AI Cost Tracking

Creating a Service Account

Why Use Service Accounts?

Creating a Service Account

Choose the Right Role

Via Dashboard

Via API

Response

Read-Only Service Account

Request Fields

Validation Rules

Common Errors

Real-World Examples

Example 1: Event Ingestion Service

Example 2: Analytics Dashboard

Example 3: Reporting or Data Warehouse Sync

Assigning Multiple Roles

Updating a Service Account

Deleting a Service Account

Best Practices

Troubleshooting

Service Getting 403 Errors

Cannot Create Service Account

Next Steps

Generate API Keys

​Why Use Service Accounts?

​Creating a Service Account

​Choose the Right Role

​Via Dashboard

​Via API

​Response

​Read-Only Service Account

​Request Fields

​Validation Rules

​Common Errors

​Real-World Examples

​Example 1: Event Ingestion Service

​Example 2: Analytics Dashboard

​Example 3: Reporting or Data Warehouse Sync

​Assigning Multiple Roles

​Updating a Service Account

​Deleting a Service Account

​Best Practices

​Troubleshooting

​Service Getting 403 Errors

​Cannot Create Service Account

​Next Steps

Generate API Keys

Why Use Service Accounts?

Creating a Service Account

Choose the Right Role

Via Dashboard

Via API

Response

Read-Only Service Account

Request Fields

Validation Rules

Common Errors

Real-World Examples

Example 1: Event Ingestion Service

Example 2: Analytics Dashboard

Example 3: Reporting or Data Warehouse Sync

Assigning Multiple Roles

Updating a Service Account

Deleting a Service Account

Best Practices

Troubleshooting

Service Getting 403 Errors

Cannot Create Service Account

Next Steps