Service accounts

A service account is a member of your company that a program acts as: an integration, a script, a connector for an assistant. It has no password, no email address and no session, and it never signs in to the interface. It calls the API with a token, and everything it does lands in issue history and in the company's audit trail under its own name.

How it differs from a person#

There is no need to create a person's account "for the integration". Somebody knows its password, it occupies a seat, and nothing in the audit trail tells a program apart from the colleague whose name it borrowed. A service account says plainly that a program did it.

Create one#

Service accounts are managed by anyone with the company right "Edit service accounts" (serviceaccounts.edit). Company administrators have it from the start.

1. Open Administration, then Service accounts.
2. Click "Create service account" and give it a name people will recognize in the audit trail, such as "Claude connector".
3. Give the account a role in the projects it will work in, either on the project's member list or through a group.

If the company has already used every service account its plan allows, creating another is rejected with identity.seats_exhausted. A deactivated or deleted account frees a slot.

Tokens#

A token is a string that starts with qvl_. The program sends it with every request:

Authorization: Bearer qvl_...

1. On the account's card, click "Mint a token".
2. Name it after where it will live, so it still makes sense six months from now, for example "MCP production".
3. Choose the token's rights: "All rights of the account" or "Chosen rights" (see below).
4. Copy the value and click "I copied it". You see a token once. We keep only its hash, so neither you nor we will ever see it again.

A token does not expire. It works until somebody revokes it. The card shows when each token was issued and when it was last used, and a token revoked with "Revoke" stops working on the very next request.

A token belongs to the company that issued it and works only at that company's address, https://<key>.quevell.com/api. Sent to another company's address, it is rejected with auth.tenant_mismatch.

To replace a token without downtime, mint a new one, switch the program over, then revoke the old one. An account can hold several tokens at once.

Token rights#

A token can never do more than its account. "All rights of the account" means exactly what the account may do in projects right now. "Chosen rights" narrows the token to the ones you pick:

A narrowed token can do only what both the rights you picked and the account's project role allow. You cannot give a token a right the account does not have.

The token remembers its list of rights, but the account's roles are read on every request. Take the account off a project or out of a group, and every token it already has loses that access on the next call. Nothing needs to be reissued.

The account's own rights#

An account gets project roles the way a person does: directly or through a group. Groups pay off when one integration works across a dozen projects.

Company rights never reach a service account, neither directly nor through a group, so no token administers the company. A service account is never added to the "Super-admin" group; trying returns identity.service_account_not_administrator.

OAuth clients#

Some programs, assistant connectors among them, will not take a long-lived token and fetch a short-lived one over OAuth 2.0 instead. For those, the account's card has "Create an OAuth client".

1. Name the client and choose its rights, just as for a token.
2. Copy the client_id (starts with qvc_) and the client_secret (starts with qvs_). You see the secret once.
3. The program trades them for a token:

curl -X POST https://<key>.quevell.com/api/oauth/token \
  -u "qvc_...:qvs_..." \
  -d grant_type=client_credentials

The response carries an access_token good for 60 minutes, token_type Bearer and expires_in. There is no refresh token: when the hour is up, the program asks again. client_credentials is the only grant supported. A wrong id and a wrong secret get the same 401 invalid_client, so a caller holding half a pair learns nothing about the other half.

Token requests are capped at 10 a minute per client and 30 a minute per network address. An honest program needs about one an hour. Past the cap the answer is 429 with oauth.rate_limited and a Retry-After header.

Tokens handed out by a client are not listed among the account's tokens: they are short-lived copies, not credentials of their own. Revoking a client revokes every token it has issued.

Deactivate and delete#

An action that does not fit the account's state is rejected with a code that names the state: identity.service_account_deactivated, identity.service_account_active or identity.service_account_deleted.

After deletion, what the account did stays in issue history and in the audit trail under the name it had.

Limits#

Service accounts are limited both in how often they call and in how much they write per day: 120 calls a minute per account, 600 for all of a company's accounts together, 10 000 records a day per account and 50 000 for the company. How the limits are counted and what a rejection looks like is in Limits in the API article.