Service accounts allow automated systems and integrations to authenticate against the Phonemos API without a human user logging in interactively. Phonemos uses Keycloak as its identity provider; all token management happens there.
Approaches
There are two main approaches, depending on your needs:
Client credentials — create a Keycloak client with service accounts enabled. The client authenticates using its own client ID and secret, with no user involved. This is the recommended approach for machine-to-machine integrations. Requires correct Hasura claim mappers to be configured on the client in Keycloak so that roles are present in the JWT.
Client needs to have to “hasura” scope set as default
Service account user settings: Under “Service Account Roles” → manage details, click on username
The user needs to have an email in keycloak (does not receive emails, use something like serviceaccount@local). Make sure to also check the “Email verified” option.
Add the user to a group that has permissions in phonemos
Note that after the service account first authenticates, it may take some time until the user is fully synced and visible in Phonemos. You can call the GraphQL mutation refresh_users to manually sync the user.
Dedicated user account (not recommended) — create a regular Keycloak user that represents the service. Simpler to set up and gives the service a Phonemos identity (visible in audit logs, assignable to permissions). Tokens are obtained via the Resource Owner Password Credentials (ROPC) grant — suitable for trusted internal systems, though note that ROPC is deprecated in OAuth 2.1 and not recommended for new integrations.
Granting access in Phonemos
Creating the account in Keycloak is not enough — the service account user must also be granted access within Phonemos itself. This can be done in two ways:
Group membership — add the user to a Phonemos group that has the required permissions on the relevant topics or zones
Individual permission — grant the user direct access on specific objects. If the (service) user is not visible then make sure that it is in a group that makes you see it (see ). It’s good practice to create a group for service accounts and the admins with visibility peers to ensure only admins can see the service accounts.
Without this step, the service account will authenticate successfully but will not be able to access any content.
Assigning roles
The service account must be assigned the appropriate roles from the phonemos-hasura client in Keycloak, either directly or via groups. Use the least-privileged roles needed for your use case (see what the API requires):
viewer — read-only access
editor — read and write access to content
manager — site and topic management, editing metadata schema
restorer — content restoration (restore from trash)
Obtaining a token
Token endpoint (replace {baseUrl} and {realm} for your instance):
1
POST {baseUrl}/realms/{realm}/protocol/openid-connect/tokenClient credentials flow (recommended):
1
2
3
grant_type=client_credentials
client_id=<your-client-id>
client_secret=<your-client-secret>The response contains an access_token to be used as the Bearer token in API requests. Tokens are short-lived; use the returned expires_in to refresh proactively, or use the refresh_token with grant_type=refresh_token to obtain a new one without re-authenticating.
You may use a token, certificates or a signed JWT to authenticate the service account.
Keycloak Admin Console
Service accounts and clients are managed in the Keycloak admin console, typically available when you click “Manage Users” from the settings menu inside Phonemos (cog wheel in the heading bar).
See https://www.keycloak.org/docs/latest/server_admin/index.html#_client-credentials on how to configure the the credentials for the service account and