A service account lets your own agent, script or pipeline use 50heads without belonging to a person. It belongs to your organization, so it keeps working when the person who set it up leaves the company, even when your identity provider removes them.

Each service account has its own client ID and secret, works in one of your teams, does only what its scopes allow, and spends only within its caps. Its questions belong to that team and use the team's credits.

We're rolling service accounts out to organizations gradually. If you don't see Service accounts in Settings, then Organization, they aren't on for your organization yet. Contact us if you'd like them.

Who can make and change them

Owners and admins of one of the organization's teams, signed in on the website. Making, changing, turning off and deleting a service account need a fresh check that it's you. Choose Confirm it's you when asked. The check lasts 10 minutes.

A service account can never make, change or widen itself or another one. Neither can an API key or a connected app.

Make a service account

  1. Go to Settings, then Organization, and choose Manage service accounts.
  2. Under New service account, give it a name that says what it's for, such as "Nightly research agent".
  3. Choose the team it works in, if your organization has more than one.
  4. Tick what it can do. Give it only what it needs.
  5. Set a daily limit and, if you like, a per-question limit, in credits.
  6. Choose how it signs in: a client secret, or a private key (see below).
  7. Choose Make service account.

The client secret is shown once, with the client ID and the token address. Copy them into your agent's settings right away. We keep only a hash of the secret, so we can't show it again. If it's lost, make a new one.

What it can do

A service account can hold any scope an API key can, listed in API keys. In its team it acts with the admin role, limited by those scopes. It's never the team's owner and is never listed as a member.

The organization scopes let it read and manage the organization within limits:

Scope What it allows
organization:read See the organization, its domains, sign-in rules, single sign-on, SCIM and service accounts
organization:write Change domains, sign-in rules and SCIM settings
members:read See where a member is signed in
members:write Sign a member out everywhere
audit:read Read and export the audit log

Some acts always need a person who has just confirmed it's them, whatever the scopes: setting up or changing the single sign-on connection and turning it on or off, making it required, testing it, changing break-glass owners, making or replacing SCIM tokens, changing how long audit events are kept, placing or releasing legal holds, handing a team to a new owner, and anything about service accounts themselves.

Spend caps

Every service account has a daily limit, and can have a per-question limit, in credits. An ask that would go over either is refused before anything is spent, exactly as for an API key. Each ask needs an Idempotency-Key; sending the same key again returns the same question and never charges twice.

How it signs in

Your agent asks the token address, https://auth.50heads.com/token, for an access token with grant_type=client_credentials. The token lasts an hour; when it runs out, the agent asks again. There's no refresh token.

With a client secret, send the client ID and secret with HTTP Basic authentication:

curl -s https://auth.50heads.com/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Then call the API with Authorization: Bearer <access_token>, as with an API key. You can add scope= to ask for fewer scopes than it has, never more.

With a private key, your agent signs a short assertion (private_key_jwt, ES256 or RS256) instead of sending a secret. Give 50heads only the public keys, as a JSON Web Key Set of up to 5 keys. Never paste a private key. The assertion's issuer and subject are the client ID, its audience is the token address, it's at most five minutes old, and each one is used once.

Replace a secret

Choose New secret on the service account. The old secret keeps working for the time you choose (24 hours by default, up to a week, or not at all), so you can switch your agent over. At most two secrets work at once. End this secret stops an old one right away.

Turn one off or delete it

  • Turn off stops its tokens on their next request and it gets no new ones. Turn on brings it back.
  • Delete stops its tokens and secrets for good, and any webhook endpoints it made. The questions it asked stay with the team, and it stays in the audit log.

Removing a person, by hand or through your identity provider, never affects a service account.

In the audit log

Every change to a service account is recorded with the person who made it. What a service account does itself, such as asking a question, adding a domain or exporting the audit log, is recorded with its name and the actor type service_account. See The audit log.