Skip to main content

Service clients

Route: /administration (Service clients) · Role: admin

A service client is a machine identity for server-to-server calls. It exchanges its client id and secret for a short-lived access token using the OpenAPI-compatible client-credentials grant.

Create a client​

  1. Open Administration → Service clients.

  2. Fill in:

    FieldNotes
    Display nameHuman label, e.g. Accounting sync.
    client-idLowercase letters, digits, and dashes (3–64 chars).
    Roleengineer, reviewer, finance, or admin.
    scopesComma-separated; see below.

  3. Click Create client.

  4. Copy the secret now — it is shown once.

Get an access token​

curl -s -X POST https://intranet.example/api/v1/auth/token \
  -H 'content-type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"accounting-sync","client_secret":"..."}'

The response contains a short-lived opaque access token carrying the client's role and scopes. Send it as Authorization: Bearer <token>.

Scopes​

The same scope vocabulary as personal tokens:

customers:read  projects:read  time:read  time:review
agreements:read billing:read   billing:write reports:read  admin:read

A read-only accounting integration typically needs billing:read and reports:read.

Delete a client​

Click Delete on the row. The client and its ability to exchange credentials are removed; existing issued tokens expire on their own.

No rotation yet

To rotate a secret, delete and recreate the client, or issue a second client for the cutover window.

Rules​

  • Secrets are scrypt-hashed; only the hash is stored.
  • The client's role is enforced exactly like a user's.
  • Issued tokens are short-lived by design — fetch a new one per call window.