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 a service account 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. A service account cannot be the account owner. Service accounts are independent of how people sign in: turning password sign-in off, or turning single sign-on on, leaves them untouched. Administrators manage service accounts on the Admin › Service accounts page.

Service accounts and integration tokens

Search2o has two kinds of long-lived credential. The right one 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 names.
3. Choose a role: user, developer or administrator. The least the program needs is best; 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, labelled with the service account's name. Please copy the key right away: it is shown only this once and is stored nowhere in Search2o. Select Copy key and put the key straight into wherever the program reads its secrets, a secret manager or an environment variable on the machine that runs the program. A chat message, a ticket or source control is no place for it.

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

Using the key

The program sends the key with every request, in an Authorization header. There is no sign-in call and no session. Every call to your agent server's 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. A few things only a person can do, such as changing a password, are refused for a service account whatever its role.

A key does not expire. The key 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, it is worth checking 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 the key has been lost, when the key 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, labelled 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. A program that must keep running without a gap is best updated 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 whenever someone who had access to the key leaves, or if the key may have been exposed.
• Removing a person from Search2o, or from your identity provider, leaves service accounts untouched. The Service accounts page is worth a review 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.