Skip to main content
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:
RoleUse When
super_adminYour service needs full, unrestricted access (treat the key as a root credential)
event_ingestorYour service needs to send events to Flexprice
event_readerYour service needs to read event data

​
Via Dashboard

Navigate to Developers > Service Accounts and click Create to open the service account creation dialog.
Create Service Account
In the dialog:
  1. Select the roles you want to assign (Event Ingestor, Event Reader, or both)
  2. 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"]
}'

​
Response

{
  "id": "usr_abc123",
  "type": "service_account",
  "roles": ["event_ingestor"],
  "created_at": "2025-11-14T10:00:00Z"
}
Save the id from the response. You’ll need it when creating API keys.

​
Request Fields

​
type
string
required
Must be set to "service_account".
​
roles
array
required
List of roles to assign. Must include at least one role.Available roles:
  • super_admin - Full access to every resource
  • event_ingestor - Can send events
  • event_reader - Can read events
​
name
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"
}

​
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)

​
Assigning Multiple Roles

You can assign both roles 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)"
}'
To rotate which roles a service account has, create a new service account with the new role set and migrate the API key over.

​
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:
  1. The service account doesn’t have the required role
  2. The API key was created before you assigned roles
  3. The role doesn’t include permission for that endpoint
Solution:
  1. Check what roles the service account has: GET /v1/users/usr_abc123
  2. Verify those roles include the permission you need
  3. 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:
  1. Forgot to include roles in the request
  2. Used an invalid role name
  3. 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 →