Service accounts and API tokens

This page explains how scripts, integrations and other systems get access to the MicroB2B REST API. They use a service account: an account for a machine, not a person.

What a service account is

A service account:

• is used only for the REST API. It never signs in to the web UI.
• appears as sa:<name> in the logs and the audit log.
• is not affected by anything that happens to a person’s user account.
• can be disabled or deleted in one place.

A service account is an administrator. MicroB2B has no permissions. Whoever holds its credential can do anything in MicroB2B. Guard its tokens like an administrator password.

Two kinds

You choose the kind when you create the account. You cannot change it later.

Use a local account unless your systems already get tokens from an identity provider.

Creating a service account

1. Go to Access > Service accounts and click New service account.
2. Fill in the settings below and save.

On the command line:

microb2b service-accounts create ci-deploy --description "Deploys from the CI pipeline"

API tokens

A local account can have several API tokens. So you can make a new token before you revoke the old one.

Making a token

1. Open the account from Access > Service accounts.
2. Click Make token.
3. Enter a Label that says where the token is used, for example ci runner 2.
4. Set Expires in (days): 1 to 365, 90 by default.
5. Submit the form. MicroB2B shows the token once. Copy it before you leave the page.

On the command line:

microb2b service-accounts token create ci-deploy --label "ci runner 2" --expires-in-days 90

MicroB2B keeps only a hash of the token. A lost token cannot be shown again. Make a new one.

Every token expires. There are no tokens that last forever.

Using a token

Send the token in the Authorization header of every request:

curl -H "Authorization: Bearer mb2b_..." https://b2b.example.com/api/v1/stats

A token looks like mb2b_<id>_<secret>. The mb2b_ prefix helps secret scanners find a leaked token. The account’s page shows each token as mb2b_<id>_…, so you can tell them apart.

See API basics for how requests and responses work.

Revoking a token

• In the web UI: click Revoke in the token’s row on the account’s page and confirm.
• On the command line: microb2b service-accounts token revoke <id>.

A revoked token stops working at once. It stays in the list so you can see it.

Expiry warning

MicroB2B checks the tokens every hour. It raises the alert api_token_expiring for each working token of an enabled account that expires within 14 days. It repeats the alert once a day. Make a new token, switch your script to it, then revoke the old one. See notifications to get alerts by chat or webhook.

The account’s page and the list also show when each token and account was last used, to within a minute.

Federated service accounts

A federated account uses access tokens from an identity provider. MicroB2B registers nothing by itself. A token whose subject is not registered is refused, however valid it is.

Setting up the provider

Add the provider on Access > Identity providers. See identity providers. For a provider that only serves machines:

• Turn Offer sign-in off. The provider then needs no client ID or secret and shows no button on the login page.
• The token’s audience (aud) must contain the provider’s API Audience. A token for another audience is always refused.
• Some providers issue machine tokens without an audience. For those, turn Accept tokens without an audience on. This applies to federated service accounts only, never to people.
• Set Required API scopes to scopes every token must carry. Without an audience, these scopes are what ties a token to MicroB2B. Always set them when you accept tokens without an audience.

Registering the account

Create a service account with Kind set to Federated (identity provider). Choose the provider and enter the token’s Subject exactly.

On the command line:

microb2b service-accounts create importer --issuer https://idp.example.com/realms/b2b --subject 3f2a...

Example: Amazon Cognito

Cognito machine clients use the client credentials grant. Their tokens come from https://cognito-idp.<region>.amazonaws.com/<user pool id>. They carry no audience, name the app client in sub and the API in scope.

1. In Cognito, give the user pool a domain. The token endpoint is there.
2. Add a resource server with identifier microb2b and a scope api.
3. For each machine, add an app client with a client secret, only the Client credentials grant, and the scope microb2b/api.
4. In MicroB2B, add an identity provider:
   • Issuer URL https://cognito-idp.<region>.amazonaws.com/<user pool id>
   • Offer sign-in off
   • Accept tokens without an audience on
   • Required API scopes microb2b/api
5. For each app client, add a federated service account with that provider. The subject is the app client ID.

The machine gets a token like this:

curl -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials -d scope=microb2b/api \
  https://<domain>.auth.<region>.amazoncognito.com/oauth2/token

It then sends Authorization: Bearer <access_token>. Keep the token until it expires (an hour by default). Do not fetch one per request: Cognito charges per token request.

Other examples

• JumpCloud service accounts
• Keycloak clients

Disabling and deleting

• Disable an account to refuse all its credentials at once. Enable restores them.
• Delete an account in the danger zone of its page. This also revokes all its tokens. A later account with the same name gets none of them.

When a request is refused

A refused request gets 401 and one of these codes:

MicroB2B logs the real reason as a warning API request refused, with a reason attribute. The reason never contains the token. See troubleshooting sign-in.

The command line

microb2b service-accounts works like microb2b users. It opens the database with DB_TYPE and DB_URL. Changes are recorded with the actor cli:<operating system user>.

What is recorded

Creating, changing and deleting accounts, and making and revoking tokens, are events in the audit log. Every log line of a request names the account and the credential it used.