Service Account Access Tokens

If you need automated systems, CI/CD pipelines, or external integrations to call the IOMETE API, service account access tokens are the way to go. They work like personal access tokens, but they're tied to a service account instead of a human user.

This guide focuses on what's different about service account tokens. For the basics of creating, suspending, and rate-limiting tokens, see the Personal Access Tokens guide.

Prerequisites

To manage service account tokens, ensure that the following prerequisites are met:

• Group membership: You must share at least one group with the service account. Without this, the token list returns a 403 error.
• Permission: Either the access_token.manage role permission (Roles), the MANAGE_ACCESS_TOKEN bundle permission (Domain Authorization), or any admin role. The Generate new token button stays disabled if you lack the required permission.

Group Membership

If you see "You must be in the same group as this service account to view and manage tokens", ask your admin to add you to one of the service account's groups.

Finding the Token Management Page

You manage service account tokens from the account's detail page. The Access Tokens tab only appears for users of type SERVICE_ACCOUNT, and you can get there in two ways.

For domain members

1. Go to Settings > Members.
2. Find and select the service account.
3. Open the Access Tokens tab.

For admins

1. Go to Admin > Users.
2. Find and select the service account.
3. Open the Access Tokens tab.

Both paths lead to the same interface. The difference is permissions: domain-level access requires the access_token.manage role permission, while admin-level access is open to any admin user.

Managing Service Account Tokens

You create, suspend, and delete service account tokens the same way as personal tokens — with a few key differences. See the Personal Access Tokens guide for the full workflow.

• Max RPS column: The token list includes a Max RPS column (only visible for service accounts) that displays the configured requests-per-second cap, or "None" if unset.

API Endpoints

If you're calling the API directly, service account tokens use their own set of endpoints (separate from personal token endpoints). Every endpoint enforces the same-group requirement on top of standard permissions.

Domain-Level Endpoints

Base path: /api/v1/domains/{domain}/auth/service-accounts/{serviceAccountId}

Method	Path	Purpose
GET	/tokens	List tokens
POST	/tokens	Create a token
PATCH	/tokens/{name}	Update a token (status, maxRps)
DELETE	/tokens/{name}	Delete a token

Requires access_token.manage (role v1) or MANAGE_ACCESS_TOKEN (bundle v2), plus same-group membership.

Admin-Level Endpoints

Base path: /api/v1/auth/service-accounts/{serviceAccountId}

Method	Path	Purpose
GET	/tokens	List tokens
POST	/tokens	Create a token
PATCH	/tokens/{name}	Update a token (status, maxRps)
DELETE	/tokens/{name}	Delete a token

Requires any admin role, plus same-group membership.

Deprecated Endpoint

The older POST /service-accounts/tokens endpoint (with serviceAccountId in the request body) is deprecated. Use the path-parameter versions above instead.

Access Permissions

Different permission models control who can manage service account tokens. The same-group check applies in all contexts, even for admins.

Context	Required Permission	Same-Group Required
Domain, role-based (v1)	access_token.manage	Yes
Domain, bundle-based (v2)	MANAGE_ACCESS_TOKEN	Yes
Admin	Any admin role	Yes

Configure access_token.manage through Roles, or MANAGE_ACCESS_TOKEN through Domain Authorization.