Service accounts

A service account is a user that is a program rather than a person. A script, a scheduled job or a back-end integration uses one to call the Search2o API on its own behalf, with a key instead of a password.

A service account has its own role (user, developer or administrator) and can do what that role allows. It cannot be the account owner. Service accounts do not depend on how people sign in: turning password sign-in off, or turning single sign-on on, leaves them untouched. Administrators manage them on the Admin › Service accounts page.

Service accounts and integration tokens

Search2o has two kinds of long-lived credential. Which one to use depends on what the program is.

Integration tokens are described under Chat integrations.

Adding a service account

1. Open Admin › Service accounts.
2. Enter a name. The name identifies the service account on this page and is unique in your account: letters and digits, with _, - or . between them, starting and ending with a letter or a digit, up to 64 characters. daily_sync, billing-export and ci.deploy are all valid.
3. Choose a role: user, developer or administrator. Give the program the least it needs; the role can be changed later.
4. Optionally enter an email. Without one, the service account is given <name>@service, for example daily_sync@service, an address that receives no mail. A real address must not already belong to a user.
5. Select Create.

The key appears in a highlighted panel at the top of the list, labeled with the service account's name. Copy it immediately: it is shown only this once and is stored nowhere in Search2o. Store it directly where the program reads its secrets: a secret manager or an environment variable on the machine that runs the program.

The key stays on the page until you leave it, rotate another key, or delete that service account. A lost key cannot be recovered; rotate it instead.

Using the key

The program sends the key with every request, in an Authorization header. The key alone authenticates each call; nothing is signed in and nothing expires. Every call under /api/ is a POST with a JSON body. Finding an agent for a question, for example:

$ curl -s -X POST https://search2o.example.com/api/exec/search \
    -H "Authorization: Bearer $SEARCH2O_SERVICE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "What is our travel expense policy?"}'

What a call may do is decided by the service account's role, exactly as for a person with that role. Some actions that only a person can take, such as changing a password, are refused for a service account whatever its role.

A key does not expire. It stops working when it is rotated or when the service account is deleted, and a request with such a key is refused as unauthorized. If that happens unexpectedly, check whether someone rotated the key.

Changing the role

In the list, choose a new role in the service account's Role column. The change applies to the program's next call. Any role except owner can be chosen.

Rotating a key

Rotate a key when it has been lost, when it may have been exposed, or as routine hygiene.

1. In the list, select Rotate key on the service account's row.
2. Confirm. The current key stops working immediately, so anything still using it is refused until it is given the new key.
3. The new key appears in the panel, labeled New key for the service account. Copy it as when the account was created, and update the program.

A service account has one key at a time. Update a program that must keep running as soon as the key is rotated.

Deleting a service account

1. In the list, select Delete on the service account's row.
2. Confirm. The key stops working immediately, and the service account cannot be recovered.

If the program must work again later, create a new service account and give the program the new key.

Good practice

• One service account per program, so that each can be rotated or deleted without affecting the others, and each role can be as small as that program needs.
• Keys belong in a secret manager, never in code.
• Rotate a key when someone who had access to it leaves, or if it may have been exposed.
• Removing a person from Search2o, or from your identity provider, leaves service accounts untouched. Review the Service accounts page when people with access to keys leave.

The API

Everything the page does is available to administrators through the REST API: getServiceAccounts, createServiceAccount, rotateServiceAccountKey, setServiceAccountRole and deleteServiceAccount, all under /api/admin/. The user calls updateRole and deleteUsers are for people and refuse a service account.