Skip to content

Service accounts

A service account is a member of your organisation that is not a person but a program: an integration, a script that runs at night, another system calling OS. Everything a person can do in OS, a service account can do through the API, decided in exactly the same way. This page is for administrators: those who hold the organisation's administrator role.

A key can do exactly what its service account may, and nothing more. Whoever holds a key acts as the service account. Give a service account few rights, and its keys give few rights too. So give a service account only what the program really needs.

On the screen

Open User management, choose Service accounts and go through:

  1. The list. You see your service accounts. Choose Create a service account to make one.
  2. Creating. Fill in Name and, if you like, Description, choose the roles, groups and attribute values it gets (you can only give what you hold yourself) and choose Create service account.
  3. Keys. Open the service account and choose the Keys tab. Choose Create a new API key, fill in API Key name and Expiry date and choose Create API key. The screen shows the Secret once, with the Client id and the Token endpoint: keep it at once. Each key shows its status, when it expires, when it was last used and its warnings. When a key expires within 14 days, the organisation's administrators also get a notification in OS and by mail, once per expiry date. The old copy of a rotated key does not warn.
  4. Rotating. On an active key choose Rotate, fill in the new expiry date and the Overlap in hours and confirm. The screen shows the new secret once. Only someone who holds everything the service account holds gets this button.
  5. Revoking. On a key choose the bin and confirm. The key stops working.
  6. Rights. The Rights tab shows the service account's roles, groups and attribute values. Choose Add rights to give some, or take one back; you can only give and take back what you may yourself.
  7. Access. The Access tab shows what the service account may do per kind of thing (See, Use, Change, Delete), and so also what whoever holds its key can do. Look here before you make a key.
  8. Deactivating and deleting. At the top of the page choose Deactivate (or Activate) or Delete.

Make a service account

  1. Choose a name (unique in your organisation) and, if you like, a description of what it is for.
  2. Choose the roles, groups and attribute values it gets, as for an invitation. You can only give what you hold yourself (why).
  3. The service account is active at once. Nobody has to accept an invitation.

A service account is in the same member list as the people, with the same roles, groups and attributes. Only who manages service accounts changes them, the same way as for a person; a people administrator sees a service account in the list but changes nothing of it. A service account does not count as the last administrator: an organisation always keeps a person holding the administrator role.

What a service account cannot do

What a person does only for themselves, a service account cannot: set preferences, ask for its own erasure and accept an invitation. OS refuses these with 403. A service account is managed and removed by an administrator.

Keys

A program signs in with a key. A service account can hold several keys (at most five at a time by default), each with a name of its own.

  1. Make a key with a name and an expiry date. It is required and lies at most a year ahead.
  2. OS shows the key's secret once, with the client id and the address where the program asks for a token. Store the secret somewhere safe at once; OS never shows it again.
  3. After a few seconds the key works.

Only whoever holds everything the service account holds may make a key for it. That way nobody gains more rights through a key than they already have.

The program asks for a token with the client id and the secret, and sends that token to OS:

curl -s -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

A token is valid for five minutes; the program then asks for a new one.

Replace a key without interruption

Rotate a key: OS makes a new key with a new secret, and the old one keeps working for an overlap (24 hours by default, at most 30 days). Put the new secret in the program before the overlap ends.

Revoking, expiry and warnings

  • A revoked key stops working from the next request.
  • An expired key stops working from its expiry date.
  • Each key shows when OS last saw it used (to within five minutes). OS warns about a key that expires within 14 days, that has not been used for 30 days, or that was never used a week after it was made.

Use over MCP

Your own agent that speaks MCP can work with OS as the service account, with the account's rights: every operation of OS's API is then a tool. Open the service account; on the General tab, Use over MCP shows:

  • the MCP address, where the agent sends its calls;
  • the Token address, where the agent gets a token;
  • Get a token and List the tools: two examples to copy.

Use the client ID of a key on the Keys tab and that key's secret. Put the secret where YOUR_CLIENT_SECRET stands and the token from the first step where ACCESS_TOKEN stands:

curl -s -X POST '<token address>' \
  -d grant_type=client_credentials \
  -d client_id='<client ID>' \
  -d client_secret='YOUR_CLIENT_SECRET'

curl -s -X POST '<MCP address>' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A token is valid for five minutes; then get a new one. If the service account has no active key, the card says to make one first. While AI apps are Off in the organisation, the agent has every call refused until an administrator turns it on (Working from AI apps); the card says so too.

What a service account may do and what it did

For each service account you see, per kind of thing, what it may do. In the audit trail you see what it did and what was done to the service account and its keys. Secrets are never in the trail.

Deactivate and remove

  • Deactivate: from the next request OS refuses the service account everything in the organisation, under every key; only GET /api/v1/me still answers, with no membership. Reactivating makes the same keys usable again.
  • Remove: for good. Every key is revoked. What the service account made in the AI features stays the organisation's, unless you choose to erase it.

When OS refuses

  • 401: the key is revoked or expired, or the token is another client's.
  • 403: you give a role, group or value you do not hold yourself, or you make a key for a service account that holds more than you; the message names what.
  • 409: the name is taken, the service account already holds as many keys as it may, or the service account changed in the meantime.
  • 422: an expiry date that is missing, past or too far ahead.

Via the API

  • POST /api/v1/organisations/{id}/service-accounts with name and, optionally, description, roles, groups and attributes, as for an invitation.
  • GET, PATCH (with If-Match) and DELETE /api/v1/organisations/{id}/service-accounts/{account_id}.
  • POST /api/v1/organisations/{id}/service-accounts/{account_id}/keys with label and expires_at; the answer carries client_id, client_secret and token_endpoint.
  • POST …/keys/{key_id}/rotate with expires_at and overlap_hours; DELETE …/keys/{key_id} revokes a key.
  • GET /api/v1/organisations/{id}/memberships/{account_id}/access shows what it may do; GET /api/v1/organisations/{id}/audit-events?actor={account_id} what it did.